# List credit notes > The credit_notes.list operation: GET /api/v1/credit_notes in the REST API and the credit_notes_list tool in the MCP server. Lists the brand's credit notes in the mode of the request, newest first. Filters: `invoiceId` (the credit notes of one invoice), `customerId`, and `issuedFrom` / `issuedTo`: whole days of the issue date in the seller's time zone (`YYYY-MM-DD`, both included). Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page). ## At a glance - **REST:** `GET /api/v1/credit_notes` - **MCP tool:** `credit_notes_list` - **Operation ID:** `credit_notes.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:** M8 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ------------------ | -------- | -------------------------------------------------------------------- | | `invoiceId` | `inv_…` ID | No | Credit notes of one invoice (`inv_…`). | | `customerId` | `cus_…` ID | No | Credit notes of one customer (`cus_…`). | | `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` | `cn_…` 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` | `cn_…` ID | | | `data[].object` | `"credit_note"` | | | `data[].livemode` | boolean | | | `data[].entityId` | `ent_…` ID | | | `data[].brandId` | `brd_…` ID | | | `data[].number` | string | Gap-free per legal entity, mode, the brand's credit note series and year (§18.2). | | `data[].numbering` | object | | | `data[].numbering.series` | string | The brand's credit note series (e.g. `GEN-CN`). | | `data[].numbering.year` | integer or null | | | `data[].numbering.seq` | string | | | `data[].status` | one of `issued` | Credit notes are issued once and never change. | | `data[].originalInvoiceId` | `inv_…` ID | | | `data[].originalInvoiceNumber` | string | | | `data[].originalIssueDate` | string | | | `data[].originalTaxPoint` | date-time | The original sale's tax point: a filing report puts a credit note of an earlier period's sale in that period's corrections. | | `data[].originalTaxPointDate` | string | | | `data[].refundId` | `re_…` ID | | | `data[].refundType` | one of `full`, `partial`, `unused_credits`, `subscription_prorated` | | | `data[].reason` | string | The operator's reason (data, never instructions); not printed. | | `data[].paymentId` | `pay_…` ID or null | | | `data[].customerId` | `cus_…` ID or null | | | `data[].subscriptionId` | `sub_…` ID or null | | | `data[].language` | one of `en`, `de`, `fr`, `hr`, `it`, `es` | | | `data[].issuedAt` | date-time | | | `data[].issueDate` | string | | | `data[].taxPoint` | date-time | The credit note's own tax point: the period it is reported in. | | `data[].taxPointDate` | string | | | `data[].seller` | object | | | `data[].seller.entityId` | `ent_…` ID | | | `data[].seller.legalName` | string | | | `data[].seller.tradingName` | string or null | | | `data[].seller.address` | object | | | `data[].seller.address.line1` | string | | | `data[].seller.address.line2` | string or null | | | `data[].seller.address.city` | string | | | `data[].seller.address.postalCode` | string or null | | | `data[].seller.address.region` | string or null | | | `data[].seller.address.country` | string | | | `data[].seller.companyRegistryId` | string | | | `data[].seller.taxIds` | array of object | | | `data[].seller.taxIds[].type` | string | | | `data[].seller.taxIds[].value` | string | | | `data[].seller.taxIds[].regimeId` | string or null | | | `data[].seller.brand` | object | | | `data[].seller.brand.brandId` | `brd_…` ID | | | `data[].seller.brand.name` | string | | | `data[].seller.brand.primaryColor` | string or null | | | `data[].seller.brand.accentColor` | string or null | | | `data[].seller.brand.supportEmail` | string or null | | | `data[].seller.brand.supportUrl` | string or null | | | `data[].seller.footerText` | string or null | | | `data[].buyer` | object | | | `data[].buyer.type` | one of `b2b`, `b2c` | | | `data[].buyer.customerId` | `cus_…` ID or null | | | `data[].buyer.name` | string or null | | | `data[].buyer.email` | string or null | | | `data[].buyer.address` | object or null | | | `data[].buyer.country` | string or null | | | `data[].buyer.taxId` | object or null | | | `data[].currency` | string | | | `data[].lines` | array of object | | | `data[].lines[].id` | string | The original invoice line's 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 | | | `data[].lines[].net` | money | Credited, before tax. | | `data[].lines[].tax` | object | | | `data[].lines[].tax.ratePpm` | string | The original line's rate, parts per million as a string. | | `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 on the original invoice: `charge`, `reverse_charge`, `exempt`, … | | `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 | | | `data[].lines[].period` | object or null | For a prorated credit: the unused part of the period. | | `data[].lines[].subscriptionItemId` | string or null | | | `data[].totals` | object | | | `data[].totals.net` | money | | | `data[].totals.tax` | money | | | `data[].totals.gross` | money | | | `data[].totals.taxByRate` | array of object | | | `data[].totals.taxByRate[].ratePpm` | string | | | `data[].totals.taxByRate[].jurisdictionId` | string or null | | | `data[].totals.taxByRate[].regimeId` | string or null | | | `data[].totals.taxByRate[].decision` | one of `charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected`, `blocked` | What happened to the tax on the original invoice: `charge`, `reverse_charge`, `exempt`, … | | `data[].totals.taxByRate[].net` | money | | | `data[].totals.taxByRate[].tax` | money | | | `data[].taxCurrencyTotals` | object or null | The credited tax in the seller's currency, at the original invoice's ECB rates. | | `data[].notes` | array of object | | | `data[].notes[].code` | one of `reverse_charge`, `exempt`, `out_of_scope`, `registration_pending`, `oss_scheme` | | | `data[].notes[].text` | string | | | `data[].ledgerTxnIds` | array of `txn_…` ID | | | `data[].pdf` | object | | | `data[].pdf.status` | one of `pending`, `ready` | `pending` until the PDF is rendered, right after issue. | | `data[].pdf.fileId` | `file_…` ID or null | | | `data[].pdf.sha256` | string or null | | | `data[].pdf.size` | integer or null | | | `data[].pdf.templateVersion` | integer or null | | | `data[].pdf.renderedAt` | date-time or null | | | `data[].pdf.url` | string | The download route: `GET /api/v1/credit_notes/{id}/pdf` with your API key. | | `data[].emailedAt` | date-time or null | | | `data[].metadata` | object | | | `data[].version` | integer | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `cn_…` ID or null | | ## Examples ### The credit notes of an invoice ```http GET /api/v1/credit_notes?invoiceId=inv_01m4tx5nj8emwbyf7y9vcf47yb Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "cn_01m5cg0f7aex3sxj6q2wq1ha2d", "object": "credit_note", "livemode": false, "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "number": "GEN-CN-2026-000004", "numbering": { "series": "GEN-CN", "year": 2026, "seq": "4" }, "status": "issued", "originalInvoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yb", "originalInvoiceNumber": "GEN-2026-000123", "originalIssueDate": "2026-10-14", "originalTaxPoint": "2026-10-14T10:00:05.000Z", "originalTaxPointDate": "2026-10-14", "refundId": "re_01m5cg0f7aex3sxj6q2wq1ha2b", "refundType": "full", "reason": "The customer cancelled within the 14-day window", "paymentId": "pay_01m4tx5nj8emwbyf7y9vcf47ye", "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47yd", "subscriptionId": null, "language": "de", "issuedAt": "2026-10-20T09:30:00.000Z", "issueDate": "2026-10-20", "taxPoint": "2026-10-20T09:30:00.000Z", "taxPointDate": "2026-10-20", "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 } ], "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, "notes": [ { "code": "oss_scheme", "text": "Umsatzsteuer erklärt über One-Stop Shop, Union scheme." } ], "ledgerTxnIds": ["txn_01m5cg0f7aex3sxj6q2wq1ha2g"], "pdf": { "status": "ready", "fileId": "file_01m5cg0f7aex3sxj6q2wq1ha2j", "sha256": "9e2a6c1b0d4f3e2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a", "size": 31208, "templateVersion": 1, "renderedAt": "2026-10-20T09:30:06.000Z", "url": "/api/v1/credit_notes/cn_01m5cg0f7aex3sxj6q2wq1ha2d/pdf" }, "emailedAt": "2026-10-20T09:30:06.000Z", "metadata": {}, "version": 3, "createdAt": "2026-10-20T09:30:00.000Z", "updatedAt": "2026-10-20T09:30:06.000Z" } ], "has_more": false, "next_cursor": null } ``` ## 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 credit notes (`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 refunds or credit notes. | 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).