# List invoices > The invoices.list operation: GET /api/v1/invoices in the REST API and the invoices_list tool in the MCP server. Lists the brand's invoices and receipts in the mode of the request, drafts included, newest first, by status (`draft`, `open` and unpaid, `paid`, `void`, `uncollectible`, …), customer, subscription or issue date. Invoices that exist only: the one a subscription's next renewal will issue is `invoices.upcoming`. Filters: `customerId`, `subscriptionId`, `status` (one or several, e.g. `draft` or `open`), and `issuedFrom` / `issuedTo`: whole days of the issue date in the seller's time zone (`YYYY-MM-DD`, both included; drafts have no issue date yet). Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page). ## At a glance - **REST:** `GET /api/v1/invoices` - **MCP tool:** `invoices_list` - **Operation ID:** `invoices.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:** M4 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------- | | `customerId` | `cus_…` ID | No | Invoices of one customer (`cus_…`). | | `subscriptionId` | `sub_…` ID | No | Invoices of one subscription (`sub_…`). | | `status` | one of 9 values, e.g. `draft`, `pending_registration`, `issued` (all in the OpenAPI document) or array of one of 9 values, e.g. `draft`, `pending_registration`, `issued` (all in the OpenAPI document) | No | One status, or several. | | `issuedFrom` | string | No | Issued on or after this day (`YYYY-MM-DD`, the seller's time zone). | | `issuedTo` | string | No | Issued on or before this day (`YYYY-MM-DD`, the seller's time zone). | | `limit` | integer (1 to 100) | No | Page size, 1 to 100 (default 10). | | `starting_after` | `inv_…` 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` | `inv_…` ID | | | `data[].object` | `"invoice"` | | | `data[].livemode` | boolean | | | `data[].entityId` | `ent_…` ID | | | `data[].brandId` | `brd_…` ID | | | `data[].number` | string or null | The invoice number: gap-free per legal entity, mode, brand series and year (§18.2). Null for a draft: the number is taken at finalization. | | `data[].numbering` | object or null | | | `data[].customerId` | `cus_…` ID or null | | | `data[].subscriptionId` | `sub_…` ID or null | | | `data[].collectionMethod` | one of `charge_automatically`, `send_invoice` | | | `data[].kind` | one of `invoice`, `receipt` or null | `invoice` (business customers) or `receipt` (the receipt-invoice consumers get); null for a draft. | | `data[].status` | one of 9 values, e.g. `draft`, `pending_registration`, `issued` (all in the OpenAPI document) | `draft` → `open` (finalized) → `paid`, `void` or `uncollectible`. Checkout invoices are `issued` (paid at once), or `pending_registration`: a full invoice charged before the tax registration exists; the receipt went out and the formal invoice follows (§18.1). | | `data[].language` | one of `en`, `de`, `fr`, `hr`, `it`, `es` or null | | | `data[].issuedAt` | date-time or null | | | `data[].issueDate` | string or null | The issue date in the seller's time zone. | | `data[].taxPoint` | date-time or null | | | `data[].taxPointDate` | string or null | The date of supply in the seller's time zone. | | `data[].daysUntilDue` | integer or null | send_invoice: days from the issue date to the due date. | | `data[].dueDate` | string or null | send_invoice: when payment is due (fixed at finalization). | | `data[].seller` | object or null | | | `data[].buyer` | object or null | | | `data[].currency` | string | | | `data[].lines` | array of object | | | `data[].lines[].id` | string | The tax quote's line ID. | | `data[].lines[].description` | string | | | `data[].lines[].productId` | `prod_…` ID or null | | | `data[].lines[].priceId` | `price_…` ID or null | | | `data[].lines[].quantity` | integer | | | `data[].lines[].taxCategoryId` | one of 9 values, e.g. `electronically_supplied_service`, `saas`, `ebook` (all in the OpenAPI document) | | | `data[].lines[].taxBehavior` | one of `inclusive`, `exclusive` | | | `data[].lines[].unitAmount` | money | The net price of one unit (may be finer than the minor unit). | | `data[].lines[].net` | money | | | `data[].lines[].tax` | object | | | `data[].lines[].tax.ratePpm` | string | Parts per million as a string (19% = "190000"). | | `data[].lines[].tax.amount` | money | | | `data[].lines[].tax.jurisdictionId` | string or null | | | `data[].lines[].tax.regimeId` | string or null | | | `data[].lines[].tax.decision` | one of `charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected`, `blocked` | What happened to the tax: `charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected`. | | `data[].lines[].tax.rateKind` | one of `standard`, `reduced`, `super_reduced`, `parking`, `zero`, `exempt`, `not_taxable` or null | | | `data[].lines[].tax.rateId` | string or null | | | `data[].lines[].tax.pendingRegistration` | boolean | | | `data[].lines[].gross` | money | | | `data[].lines[].kind` | one of `licensed`, `metered`, `late_usage`, `proration`, `invoice_item` or null | Where the line came from (§16.3 order); null on checkout invoices. | | `data[].lines[].period` | object or null | | | `data[].lines[].subscriptionItemId` | string or null | | | `data[].lines[].invoiceItemId` | `ii_…` ID or null | | | `data[].lines[].discount` | money or null | What discounts took off the line before tax. | | `data[].lines[].meteredQuantity` | string or null | A metered line's usage (its quantity is 1). | | `data[].totals` | object or null | | | `data[].taxCurrencyTotals` | object or null | The tax in the seller's tax currency when the invoice is in another one (§18.3). | | `data[].creditApplied` | money or null | Taken from the customer's credit balance at finalization (§16.11). | | `data[].amountDue` | money or null | What the customer pays: the gross total less the credit applied. Null on checkout invoices. | | `data[].notes` | array of object | | | `data[].notes[].code` | one of `reverse_charge`, `exempt`, `out_of_scope`, `registration_pending`, `oss_scheme` | | | `data[].notes[].text` | string | The note as printed. | | `data[].fieldCheck` | object or null | What the knowledge base's invoicing rules ask for that the invoice lacks (`missing`), and requirements Ownrecord can't check yet (`unchecked`). | | `data[].pendingRegistration` | boolean | A full invoice with a line charged before the registration exists (§18.1). | | `data[].paymentIds` | array of `pay_…` ID | | | `data[].creditNoteIds` | array of `cn_…` ID | | | `data[].ledgerTxnIds` | array of `txn_…` ID | | | `data[].quoteId` | `tq_…` ID or null | The tax quote the invoice shows (null for a draft). | | `data[].quoteIds` | array of `tq_…` ID | Every quote of the invoice: lines taxed at another date (prorations) have their own quote. | | `data[].pdf` | object or null | Null for a draft: the PDF is rendered at finalization. | | `data[].finalizedAt` | date-time or null | | | `data[].paidAt` | date-time or null | | | `data[].payment` | object or null | How the invoice was paid: `bank_transfer` (marked paid), `processor` (a card or debit payment) or `credit_balance`. | | `data[].voidedAt` | date-time or null | | | `data[].markedUncollectibleAt` | date-time or null | | | `data[].emailedAt` | date-time or null | | | `data[].sentAt` | date-time or null | When `invoices.send` last emailed the invoice. | | `data[].draft` | object or null | A draft's lines before tax (tax is quoted at finalization); null once finalized. | | `data[].metadata` | object | | | `data[].version` | integer | Pass it as `expectedVersion` to refuse a change if the invoice changed. Rendering the PDF and emailing the invoice change it too. | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `inv_…` ID or null | | ## Examples ### A customer's invoices in October 2026 ```http GET /api/v1/invoices?customerId=cus_01m4tx5nj8emwbyf7y9vcf47yd&issuedFrom=2026-10-01&issuedTo=2026-10-31 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "inv_01m4tx5nj8emwbyf7y9vcf47yb", "object": "invoice", "livemode": false, "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "number": "GEN-2026-000123", "numbering": { "series": "GEN", "year": 2026, "seq": "123" }, "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47yd", "subscriptionId": null, "collectionMethod": "charge_automatically", "kind": "receipt", "status": "issued", "language": "de", "issuedAt": "2026-10-14T10:00:05.000Z", "issueDate": "2026-10-14", "taxPoint": "2026-10-14T10:00:05.000Z", "taxPointDate": "2026-10-14", "daysUntilDue": null, "dueDate": null, "seller": { "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "legalName": "Acme Digital d.o.o.", "tradingName": null, "address": { "line1": "Ilica 1", "line2": null, "city": "Zagreb", "postalCode": "10000", "region": null, "country": "HR" }, "companyRegistryId": "080000001", "taxIds": [ { "type": "eu_vat", "value": "HR12345678901", "regimeId": null } ], "brand": { "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "name": "Genno", "primaryColor": "#0E6B5C", "accentColor": null, "supportEmail": "help@genno.example", "supportUrl": null }, "footerText": null }, "buyer": { "type": "b2c", "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47yd", "name": "Kim Weber", "email": "kim@example.com", "address": null, "country": "DE", "taxId": null }, "currency": "EUR", "lines": [ { "id": "pro_monthly", "description": "Genno Pro, monthly", "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yh", "priceId": "price_01m4tx5nj8emwbyf7y9vcf47yj", "quantity": 1, "taxCategoryId": "saas", "taxBehavior": "exclusive", "unitAmount": { "amount": "100000000", "currency": "EUR" }, "net": { "amount": "100000000", "currency": "EUR" }, "tax": { "ratePpm": "190000", "amount": { "amount": "19000000", "currency": "EUR" }, "jurisdictionId": "DE", "regimeId": "EU_OSS_UNION", "decision": "charge", "rateKind": "standard", "rateId": null, "pendingRegistration": false }, "gross": { "amount": "119000000", "currency": "EUR" }, "kind": null, "period": null, "subscriptionItemId": null, "invoiceItemId": null, "discount": null, "meteredQuantity": null } ], "totals": { "net": { "amount": "100000000", "currency": "EUR" }, "tax": { "amount": "19000000", "currency": "EUR" }, "gross": { "amount": "119000000", "currency": "EUR" }, "taxByRate": [ { "ratePpm": "190000", "jurisdictionId": "DE", "regimeId": "EU_OSS_UNION", "decision": "charge", "net": { "amount": "100000000", "currency": "EUR" }, "tax": { "amount": "19000000", "currency": "EUR" } } ] }, "taxCurrencyTotals": null, "creditApplied": null, "amountDue": null, "notes": [ { "code": "oss_scheme", "text": "Umsatzsteuer erklärt über One-Stop Shop, Union scheme." } ], "fieldCheck": { "invoicingRuleIds": [], "missing": [], "unchecked": [] }, "pendingRegistration": false, "paymentIds": ["pay_01m4tx5nj8emwbyf7y9vcf47ye"], "creditNoteIds": [], "ledgerTxnIds": ["txn_01m4tx5nj8emwbyf7y9vcf47yf"], "quoteId": "tq_01m4tx5nj8emwbyf7y9vcf47xq", "quoteIds": ["tq_01m4tx5nj8emwbyf7y9vcf47xq"], "pdf": { "status": "ready", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47yg", "sha256": "4f1c3c3e6a2f0b9d8e7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e", "size": 27265, "templateVersion": 1, "renderedAt": "2026-10-14T10:00:09.000Z", "url": "/api/v1/invoices/inv_01m4tx5nj8emwbyf7y9vcf47yb/pdf" }, "finalizedAt": null, "paidAt": null, "payment": null, "voidedAt": null, "markedUncollectibleAt": null, "emailedAt": "2026-10-14T10:00:09.000Z", "sentAt": null, "draft": null, "metadata": {}, "version": 2, "createdAt": "2026-10-14T10:00:05.000Z", "updatedAt": "2026-10-14T10:00:09.000Z" } ], "has_more": false, "next_cursor": null } ``` ### Invoices waiting for a registration number, one per page ```http GET /api/v1/invoices?status=pending_registration&limit=1 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "inv_01m4tx5nj8emwbyf7y9vcf47yb", "object": "invoice", "livemode": false, "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "number": "GEN-2026-000123", "numbering": { "series": "GEN", "year": 2026, "seq": "123" }, "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47yd", "subscriptionId": null, "collectionMethod": "charge_automatically", "kind": "invoice", "status": "pending_registration", "language": "de", "issuedAt": "2026-10-14T10:00:05.000Z", "issueDate": "2026-10-14", "taxPoint": "2026-10-14T10:00:05.000Z", "taxPointDate": "2026-10-14", "daysUntilDue": null, "dueDate": null, "seller": { "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "legalName": "Acme Digital d.o.o.", "tradingName": null, "address": { "line1": "Ilica 1", "line2": null, "city": "Zagreb", "postalCode": "10000", "region": null, "country": "HR" }, "companyRegistryId": "080000001", "taxIds": [ { "type": "eu_vat", "value": "HR12345678901", "regimeId": null } ], "brand": { "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "name": "Genno", "primaryColor": "#0E6B5C", "accentColor": null, "supportEmail": "help@genno.example", "supportUrl": null }, "footerText": null }, "buyer": { "type": "b2c", "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47yd", "name": "Kim Weber", "email": "kim@example.com", "address": null, "country": "DE", "taxId": null }, "currency": "EUR", "lines": [ { "id": "pro_monthly", "description": "Genno Pro, monthly", "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yh", "priceId": "price_01m4tx5nj8emwbyf7y9vcf47yj", "quantity": 1, "taxCategoryId": "saas", "taxBehavior": "exclusive", "unitAmount": { "amount": "100000000", "currency": "EUR" }, "net": { "amount": "100000000", "currency": "EUR" }, "tax": { "ratePpm": "190000", "amount": { "amount": "19000000", "currency": "EUR" }, "jurisdictionId": "DE", "regimeId": "EU_OSS_UNION", "decision": "charge", "rateKind": "standard", "rateId": null, "pendingRegistration": false }, "gross": { "amount": "119000000", "currency": "EUR" }, "kind": null, "period": null, "subscriptionItemId": null, "invoiceItemId": null, "discount": null, "meteredQuantity": null } ], "totals": { "net": { "amount": "100000000", "currency": "EUR" }, "tax": { "amount": "19000000", "currency": "EUR" }, "gross": { "amount": "119000000", "currency": "EUR" }, "taxByRate": [ { "ratePpm": "190000", "jurisdictionId": "DE", "regimeId": "EU_OSS_UNION", "decision": "charge", "net": { "amount": "100000000", "currency": "EUR" }, "tax": { "amount": "19000000", "currency": "EUR" } } ] }, "taxCurrencyTotals": null, "creditApplied": null, "amountDue": null, "notes": [ { "code": "oss_scheme", "text": "Umsatzsteuer erklärt über One-Stop Shop, Union scheme." } ], "fieldCheck": { "invoicingRuleIds": [], "missing": [], "unchecked": [] }, "pendingRegistration": false, "paymentIds": ["pay_01m4tx5nj8emwbyf7y9vcf47ye"], "creditNoteIds": [], "ledgerTxnIds": ["txn_01m4tx5nj8emwbyf7y9vcf47yf"], "quoteId": "tq_01m4tx5nj8emwbyf7y9vcf47xq", "quoteIds": ["tq_01m4tx5nj8emwbyf7y9vcf47xq"], "pdf": { "status": "ready", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47yg", "sha256": "4f1c3c3e6a2f0b9d8e7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e", "size": 27265, "templateVersion": 1, "renderedAt": "2026-10-14T10:00:09.000Z", "url": "/api/v1/invoices/inv_01m4tx5nj8emwbyf7y9vcf47yb/pdf" }, "finalizedAt": null, "paidAt": null, "payment": null, "voidedAt": null, "markedUncollectibleAt": null, "emailedAt": "2026-10-14T10:00:09.000Z", "sentAt": null, "draft": null, "metadata": {}, "version": 2, "createdAt": "2026-10-14T10:00:05.000Z", "updatedAt": "2026-10-14T10:00:09.000Z" } ], "has_more": true, "next_cursor": "inv_01m4tx5nj8emwbyf7y9vcf47yb" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or pagination value is invalid, or `issuedFrom` is after `issuedTo`. | Fix the fields listed in `details.issues` and send the request again. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).