# Invoice items

> Create, retrieve, update, delete, and list line items on draft invoices.

An invoice item is a single line item added to a draft invoice. You can attach items to an existing
draft or create them without an invoice to be auto-collected on the customer's next invoice.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The invoice item object

- **id** `string` — Unique identifier for the invoice item, e.g. `ii_7Yz1c4Nq`.
- **invoice** `object` (expandable) — The invoice this item belongs to, if assigned. Expand to retrieve the full object.
  - **id** `string` — Invoice identifier, e.g. `inv_4Xk9b3Mw`.
  - **status** `string` — Current status of the invoice.
- **customer** `object` (expandable) — The customer this item is billed to. Expand to retrieve the full object.
  - **id** `string` — Customer identifier, e.g. `cust_8aZ2`.
  - **email** `string` — Email address on the customer record.
- **amount** `integer` — Total amount for this line item, in the smallest currency unit (e.g. cents).
- **currency** `string` — Three-letter [ISO currency code](/docs/payments/payment-methods), e.g. `EUR`.
- **description** `string` — Human-readable description of the item, shown on the invoice.
- **quantity** `integer` — Number of units. Defaults to `1`.
- **unit\_amount** `integer` — Per-unit amount in the smallest currency unit. `amount` equals `unit_amount * quantity`.
- **created** `integer` — Unix timestamp of when the item was created.

## Create an invoice item

Adds a line item to a draft invoice. Omit `invoice` to create a pending item that will be included
on the customer's next automatically generated invoice.

`POST /v1/invoice-items`

```bash
curl -X POST https://api.vinr.com/v1/invoice-items \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d customer=cust_8aZ2 \
-d amount=2500 \
-d currency=EUR \
-d description="Consulting services — May 2026" \
-d invoice=inv_4Xk9b3Mw
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const item = await vinr.invoiceItems.create({
customer: 'cust_8aZ2',
amount: 2500,
currency: 'EUR',
description: 'Consulting services — May 2026',
invoice: 'inv_4Xk9b3Mw',
});
```

```python
import vinr

item = vinr.InvoiceItem.create(
  customer="cust_8aZ2",
  amount=2500,
  currency="EUR",
  description="Consulting services — May 2026",
  invoice="inv_4Xk9b3Mw",
)
```

```ruby
item = Vinr::InvoiceItem.create(
customer: 'cust_8aZ2',
amount: 2500,
currency: 'EUR',
description: 'Consulting services — May 2026',
invoice: 'inv_4Xk9b3Mw',
)
```

```json
{
"id": "ii_7Yz1c4Nq",
"invoice": "inv_4Xk9b3Mw",
"customer": "cust_8aZ2",
"amount": 2500,
"currency": "EUR",
"description": "Consulting services — May 2026",
"quantity": 1,
"unit_amount": 2500,
"created": 1716300000
}
```

## Retrieve an invoice item

`GET /v1/invoice-items/{id}`

```bash
curl https://api.vinr.com/v1/invoice-items/ii_7Yz1c4Nq \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const item = await vinr.invoiceItems.retrieve('ii_7Yz1c4Nq');
```

```python
item = vinr.InvoiceItem.retrieve("ii_7Yz1c4Nq")
```

```ruby
item = Vinr::InvoiceItem.retrieve('ii_7Yz1c4Nq')
```

```json
{
"id": "ii_7Yz1c4Nq",
"invoice": "inv_4Xk9b3Mw",
"customer": "cust_8aZ2",
"amount": 2500,
"currency": "EUR",
"description": "Consulting services — May 2026",
"quantity": 1,
"unit_amount": 2500,
"created": 1716300000
}
```

## Update an invoice item

Updates the `description` or `amount` on a draft invoice item. Only items on draft invoices may be
modified.

`POST /v1/invoice-items/{id}`

```bash
curl -X POST https://api.vinr.com/v1/invoice-items/ii_7Yz1c4Nq \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d description="Consulting services — May 2026 (revised)" \
-d amount=3000
```

```js
const item = await vinr.invoiceItems.update('ii_7Yz1c4Nq', {
description: 'Consulting services — May 2026 (revised)',
amount: 3000,
});
```

```python
item = vinr.InvoiceItem.modify(
  "ii_7Yz1c4Nq",
  description="Consulting services — May 2026 (revised)",
  amount=3000,
)
```

```ruby
item = Vinr::InvoiceItem.update(
'ii_7Yz1c4Nq',
description: 'Consulting services — May 2026 (revised)',
amount: 3000,
)
```

```json
{
"id": "ii_7Yz1c4Nq",
"invoice": "inv_4Xk9b3Mw",
"customer": "cust_8aZ2",
"amount": 3000,
"currency": "EUR",
"description": "Consulting services — May 2026 (revised)",
"quantity": 1,
"unit_amount": 3000,
"created": 1716300000
}
```

## Delete an invoice item

Removes an item from a draft invoice. Deleted items cannot be recovered.

`DELETE /v1/invoice-items/{id}`

```bash
curl -X DELETE https://api.vinr.com/v1/invoice-items/ii_7Yz1c4Nq \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
await vinr.invoiceItems.delete('ii_7Yz1c4Nq');
```

```python
vinr.InvoiceItem.delete("ii_7Yz1c4Nq")
```

```ruby
Vinr::InvoiceItem.delete('ii_7Yz1c4Nq')
```

```json
{
"id": "ii_7Yz1c4Nq",
"deleted": true
}
```

## List invoice items

Returns invoice items, optionally filtered by customer or invoice.

`GET /v1/invoice-items`

```bash
curl "https://api.vinr.com/v1/invoice-items?customer=cust_8aZ2&invoice=inv_4Xk9b3Mw&limit=10" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const items = await vinr.invoiceItems.list({
customer: 'cust_8aZ2',
invoice: 'inv_4Xk9b3Mw',
limit: 10,
});
```

```python
items = vinr.InvoiceItem.list(
  customer="cust_8aZ2",
  invoice="inv_4Xk9b3Mw",
  limit=10,
)
```

```ruby
items = Vinr::InvoiceItem.list(
customer: 'cust_8aZ2',
invoice: 'inv_4Xk9b3Mw',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "ii_7Yz1c4Nq",
    "invoice": "inv_4Xk9b3Mw",
    "customer": "cust_8aZ2",
    "amount": 2500,
    "currency": "EUR",
    "description": "Consulting services — May 2026",
    "quantity": 1,
    "unit_amount": 2500,
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`invoiceitem.created`, `invoiceitem.updated`, and `invoiceitem.deleted`. See [Events](/docs/api-reference/events).