List credit notes · Ownrecord docs

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`	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`	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 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`	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: 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 credit notes of an invoice#

Errors#