# Invoice items tools

> MCP tools for Invoice items: invoice_items_create, invoice_items_delete, invoice_items_list.

- `invoice_items_create`: Create an invoice item
- `invoice_items_delete`: Delete an invoice item
- `invoice_items_list`: List invoice items

## `invoice_items_create`

**Create an invoice item.** Operation [`invoice_items.create`](https://ownrecord.io/docs/reference/invoice-items-create.md) · Brand level · permission `invoices:write` · risk tier `write` · since M5

Adds a line to a draft invoice (`invoiceId`), or creates a pending item that waits for the customer's next
invoice: the next subscription invoice, or a draft created with `includePendingItems`.

The item is an active one-time price (`priceId`: its product, amount, currency and tax behavior), or a product
with a `unitAmount` (`productId`, `taxBehavior` default `exclusive`), times a `quantity`. Amounts are integer
micros in whole minor units. An item on a draft is in the draft's currency and for its customer. Tax is quoted
when the invoice is finalized.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type                            | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customerId`      | ID (`cus_…`)                    | yes      | The customer (`cus_…`).                                                                                                                                                                                  |
| `invoiceId`       | ID (`inv_…`)                    | no       | A draft of the same customer and currency; without it the item is pending.                                                                                                                               |
| `priceId`         | ID (`price_…`)                  | no       | An active one-time price with a fixed amount: its product, amount, currency and tax behavior.                                                                                                            |
| `productId`       | ID (`prod_…`)                   | no       | Instead of a price: the product (its tax category and revenue account), with `unitAmount`.                                                                                                               |
| `unitAmount`      | object                          | no       | With `productId`: the price of one unit.                                                                                                                                                                 |
| `taxBehavior`     | one of `exclusive`, `inclusive` | no       | With `productId`: whether `unitAmount` includes tax (default `exclusive`).                                                                                                                               |
| `quantity`        | integer                         | no       | Whole units, 1 to 1000000 (default 1). (1–1000000)                                                                                                                                                       |
| `description`     | string                          | no       | The line's text on the invoice (default: the product's name, and the price's nickname). (1–500 characters)                                                                                               |
| `period`          | object                          | no       | The service period the item covers (shown on the invoice).                                                                                                                                               |
| `metadata`        | object                          | no       | Your own key-value pairs (at most 50 keys, values of at most 500 characters).                                                                                                                            |
| `entity_id`       | ID (`ent_…`)                    | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                                                                                 |
| `brand_id`        | ID (`brd_…`)                    | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.                                                                 |
| `idempotency_key` | string                          | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean                         | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed, both or neither of `priceId` and `productId`, an archived product, the item's customer isn't the draft's.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The customer, the invoice, the price or the product isn't this brand's in this mode (`param` names it).
- [`customer_deleted`](https://ownrecord.io/docs/reference/errors.md#customer_deleted): The customer was deleted.
- [`invoice_status_invalid`](https://ownrecord.io/docs/reference/errors.md#invoice_status_invalid): `invoiceId` names an invoice that isn't a draft.
- [`invoice_item_price_unusable`](https://ownrecord.io/docs/reference/errors.md#invoice_item_price_unusable): A price is archived, recurring, a credit pack or a custom amount (use a product with `unitAmount`).
- [`invoice_currency_mismatch`](https://ownrecord.io/docs/reference/errors.md#invoice_currency_mismatch): An item's currency isn't the invoice's.
- [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused): The idempotency key was used before for another request.
- [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no brand (an org or entity key without `Ownrecord-Brand`).
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this brand's invoices (`invoices:write`: finance, owners and admins).
- [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed): You have no live-mode access, so you can't use live invoices.

### Examples

**Add two consulting days to a draft**

Arguments:

```json
{
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yr",
  "unitAmount": {
    "amount": "600000000",
    "currency": "EUR"
  },
  "quantity": 2,
  "description": "Implementation workshop (days)",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "ii_01m4tx5nj8emwbyf7y9vcf47ys",
  "object": "invoice_item",
  "livemode": false,
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "subscriptionId": null,
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "origin": "invoice",
  "description": "Implementation workshop (days)",
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yr",
  "priceId": null,
  "taxCategoryId": "consulting_remote",
  "taxBehavior": "exclusive",
  "quantity": 2,
  "unitAmount": {
    "amount": "600000000",
    "currency": "EUR"
  },
  "amount": {
    "amount": "1200000000",
    "currency": "EUR"
  },
  "period": null,
  "proration": false,
  "taxDate": null,
  "metadata": {},
  "createdAt": "2026-10-20T08:30:00.000Z",
  "updatedAt": "2026-10-20T08:30:00.000Z"
}
```

**A setup fee for the customer's next invoice**

Arguments:

```json
{
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "priceId": "price_01m4tx5nj8emwbyf7y9vcf47yj",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "ii_01m4tx5nj8emwbyf7y9vcf47ys",
  "object": "invoice_item",
  "livemode": false,
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "subscriptionId": null,
  "invoiceId": null,
  "origin": "pending",
  "description": "Genno Pro (Setup fee)",
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yh",
  "priceId": "price_01m4tx5nj8emwbyf7y9vcf47yj",
  "taxCategoryId": "saas",
  "taxBehavior": "exclusive",
  "quantity": 1,
  "unitAmount": {
    "amount": "49000000",
    "currency": "EUR"
  },
  "amount": {
    "amount": "49000000",
    "currency": "EUR"
  },
  "period": null,
  "proration": false,
  "taxDate": null,
  "metadata": {},
  "createdAt": "2026-10-20T08:30:00.000Z",
  "updatedAt": "2026-10-20T08:30:00.000Z"
}
```

## `invoice_items_delete`

**Delete an invoice item.** Operation [`invoice_items.delete`](https://ownrecord.io/docs/reference/invoice-items-delete.md) · Brand level · permission `invoices:write` · risk tier `write` · since M5

Deletes an invoice item that isn't billed yet: a pending item, or a line of a draft. Items of a finalized or
voided invoice are part of its record and stay. Returns the deleted item.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`ii_…`)  | yes      | The invoice item ID (`ii_…`).                                                                                                                                                                            |
| `entity_id`       | ID (`ent_…`) | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                                                                                 |
| `brand_id`        | ID (`brd_…`) | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.                                                                 |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): `id` isn't an invoice item ID (`ii_…`).
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): This brand has no such invoice item in this mode.
- [`invoice_status_invalid`](https://ownrecord.io/docs/reference/errors.md#invoice_status_invalid): The item is on a finalized or voided invoice: it's part of that invoice's record.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The item changed at the same moment; retry.
- [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no brand (an org or entity key without `Ownrecord-Brand`).
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change this brand's invoices (`invoices:write`: finance, owners and admins).
- [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed): You have no live-mode access, so you can't use live invoices.

### Example

**Remove a line from a draft**

Arguments:

```json
{
  "id": "ii_01m4tx5nj8emwbyf7y9vcf47ys",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "ii_01m4tx5nj8emwbyf7y9vcf47ys",
  "object": "invoice_item",
  "livemode": false,
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "subscriptionId": null,
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "origin": "invoice",
  "description": "Implementation workshop (days)",
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yr",
  "priceId": null,
  "taxCategoryId": "consulting_remote",
  "taxBehavior": "exclusive",
  "quantity": 2,
  "unitAmount": {
    "amount": "600000000",
    "currency": "EUR"
  },
  "amount": {
    "amount": "1200000000",
    "currency": "EUR"
  },
  "period": null,
  "proration": false,
  "taxDate": null,
  "metadata": {},
  "createdAt": "2026-10-20T08:30:00.000Z",
  "updatedAt": "2026-10-20T08:30:00.000Z"
}
```

## `invoice_items_list`

**List invoice items.** Operation [`invoice_items.list`](https://ownrecord.io/docs/reference/invoice-items-list.md) · Brand level · permission `invoices:read` · risk tier `read` · since M5

Lists the brand's invoice items in the mode of the request, newest first: a customer's (`customerId`), an
invoice's (`invoiceId`), or only those waiting for an invoice (`pending=true`). Paginate with `limit` (1–100,
default 10) and `starting_after`.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type              | Required | Description                                                                                                                              |
| ---------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `customerId`     | ID (`cus_…`)      | no       | Items of one customer.                                                                                                                   |
| `invoiceId`      | ID (`inv_…`)      | no       | Items on one invoice.                                                                                                                    |
| `pending`        | boolean or string | no       | `true`: only items not on an invoice yet; `false`: only items on one.                                                                    |
| `limit`          | integer           | no       | Page size, 1 to 100 (default 10). (1–100)                                                                                                |
| `starting_after` | ID (`ii_…`)       | no       | The `next_cursor` of the previous page.                                                                                                  |
| `entity_id`      | ID (`ent_…`)      | no       | Optional: the brand's legal entity (ent\_…); `brand_id` alone is enough.                                                                 |
| `brand_id`       | ID (`brd_…`)      | no       | The brand to act on (brd\_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand. |

- **Brand:** pass `brand_id` with an organization or entity key; a brand key acts on its own brand.
- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter or pagination value is invalid, or `invoiceId` and `pending=true` are both given.
- [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no brand (an org or entity key without `Ownrecord-Brand`).
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't read this brand's invoices (`invoices:read`; every role but billing admin has it).
- [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed): You have no live-mode access, so you can't use live invoices.

### Example

**The items of a draft**

Arguments:

```json
{
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "ii_01m4tx5nj8emwbyf7y9vcf47ys",
      "object": "invoice_item",
      "livemode": false,
      "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
      "subscriptionId": null,
      "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
      "origin": "invoice",
      "description": "Implementation workshop (days)",
      "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yr",
      "priceId": null,
      "taxCategoryId": "consulting_remote",
      "taxBehavior": "exclusive",
      "quantity": 2,
      "unitAmount": {
        "amount": "600000000",
        "currency": "EUR"
      },
      "amount": {
        "amount": "1200000000",
        "currency": "EUR"
      },
      "period": null,
      "proration": false,
      "taxDate": null,
      "metadata": {},
      "createdAt": "2026-10-20T08:30:00.000Z",
      "updatedAt": "2026-10-20T08:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```