List invoice items · Ownrecord docs

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.

At a glance

REST: GET /api/v1/invoice_items
MCP tool: invoice_items_list
Operation ID: invoice_items.list
Scope: Brand
Permission: invoices:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Pagination: limit (at most 100) and starting_after
Authentication: API key with the invoices:read scope
Since: M5

Request

Query parameters

Field	Type	Required	Description
`customerId`	`cus_…` ID	No	Items of one customer.
`invoiceId`	`inv_…` ID	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 (1 to 100)	No	Page size, 1 to 100 (default 10).
`starting_after`	`ii_…` ID	No	The `next_cursor` of the previous page.

Response

200 OK with a JSON object, a page of the list (newest first):

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].id`	`ii_…` ID
`data[].object`	`"invoice_item"`
`data[].livemode`	boolean
`data[].customerId`	`cus_…` ID
`data[].subscriptionId`	`sub_…` ID or null
`data[].invoiceId`	`inv_…` ID or null	The invoice the item is on; null while it waits for the customer's next invoice.
`data[].origin`	one of `pending`, `invoice`	`invoice`: created for a draft; `pending`: created for the next invoice.
`data[].description`	string
`data[].productId`	`prod_…` ID
`data[].priceId`	`price_…` ID or null
`data[].taxCategoryId`	one of 9 values, e.g. `electronically_supplied_service`, `saas`, `ebook` (all in the OpenAPI document)
`data[].taxBehavior`	one of `inclusive`, `exclusive`
`data[].quantity`	integer
`data[].unitAmount`	money
`data[].amount`	money	Quantity × unit amount.
`data[].period`	object or null
`data[].proration`	boolean
`data[].taxDate`	date-time or null	The date whose tax rates apply (a proration's change date).
`data[].metadata`	object
`data[].createdAt`	date-time
`data[].updatedAt`	date-time
`has_more`	boolean
`next_cursor`	`ii_…` ID or null

Examples

The items of a draft

HTTP

GET /api/v1/invoice_items?invoiceId=inv_01m4tx5nj8emwbyf7y9vcf47yk
Authorization: Bearer or_test_…

Response (200):

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
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A filter or pagination value is invalid, or `invoiceId` and `pending=true` are both given.	Fix the fields listed in `details.issues` and send the request again.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`permission_denied`	403	You can't read this brand's invoices (`invoices:read`; every role but billing admin has it).	Ask an organization owner or admin for a role or scope that allows this action.
`livemode_not_allowed`	403	You have no live-mode access, so you can't use live invoices.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

The items of a draft#

Errors#