Credit notes: drafts, issuing, application against invoices, cash refunds, and PDF/XRechnung artifacts.
List credit notes
Lists the documents that carry credit, paginated and filtered with the same grammar as the invoice list. It admits BOTH crediting kinds: a corrective is a credit note plus the corrected amounts in one document, and listing only credit_note would hide every correction issued under a jurisdiction that demands the single-document shape. Statuses are the document statuses - a draft credit note has not been issued, a reversed one was itself taken back.
Required scope: credit_note.read (Read credit notes).
query Parameters
created_atFilter on created_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. created_at.gt=value; a bare created_at=value means eq.
currencyFilter on currency (string). Operators: eq, in — dot grammar, e.g. currency.in=value; a bare currency=value means eq. A bare comma-separated value is in-sugar: currency=a,b means currency.in=a,b.
customer_idFilter on customer_id (uuid). Operators: eq, in — dot grammar, e.g. customer_id.in=value; a bare customer_id=value means eq. A bare comma-separated value is in-sugar: customer_id=a,b means customer_id.in=a,b.
due_dateFilter on due_date (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. due_date.gt=value; a bare due_date=value means eq.
issued_atFilter on issued_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. issued_at.gt=value; a bare issued_at=value means eq.
numberFilter on number (string). Operators: eq, in, contains — dot grammar, e.g. number.in=value; a bare number=value means eq. A bare comma-separated value is in-sugar: number=a,b means number.in=a,b.
originFilter on origin (enum). Operators: eq, ne, in — dot grammar, e.g. origin.ne=value; a bare origin=value means eq. A bare comma-separated value is in-sugar: origin=a,b means origin.in=a,b. Legal values: subscription, manual, quote, milestone, prepaid_capture, accrual.
origin_ref_idFilter on origin_ref_id (uuid). Operators: eq, in — dot grammar, e.g. origin_ref_id.in=value; a bare origin_ref_id=value means eq. A bare comma-separated value is in-sugar: origin_ref_id=a,b means origin_ref_id.in=a,b.
original_document_idFilter on original_document_id (uuid). Operators: eq, in — dot grammar, e.g. original_document_id.in=value; a bare original_document_id=value means eq. A bare comma-separated value is in-sugar: original_document_id=a,b means original_document_id.in=a,b.
paid_atFilter on paid_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. paid_at.gt=value; a bare paid_at=value means eq.
partially_paidFilter on partially_paid (boolean). Derived boolean predicate: only partially_paid=true|false (eq).
subscription_idFilter on subscription_id (uuid). Operators: eq, in — dot grammar, e.g. subscription_id.in=value; a bare subscription_id=value means eq. A bare comma-separated value is in-sugar: subscription_id=a,b means subscription_id.in=a,b.
updated_atFilter on updated_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. updated_at.gt=value; a bare updated_at=value means eq.
includeExtra data to add to the response: tags, lines, lines.atoms, lines.atoms.tax_rule, inputs. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. tags is sent without being asked until 2026-11-30; after that date it is sent only when named here.
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
searchCase-insensitive substring match over the document number
sortOrdering: created_at, status, kind, number, issued_at, due_date, total or amount_due, each with an optional :asc/:desc suffix (default created_at:desc). total and amount_due order by (currency, amount) — an amount is meaningless without its currency. An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
statusFilter by status. Filterable fields (status, kind, customer_id, subscription_id, original_document_id, origin, currency, number, created_at, updated_at, due_date, issued_at, paid_at, partially_paid) accept apifilter operator suffixes in the dot grammar, e.g. status.in=a,b
kindFilter by document kind. Omitted on this path it defaults to invoice, so the invoice list stays the invoice list; state it to widen.
tagFilter by tag name (repeatable, containment semantics)
countsComma-separated countable fields (status, kind, currency, origin) to include per-value counts for
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List credit notes › Responses
OK
Correct an issued invoice
Restates the issued document named by original_document_id: the body names the document, which of its priced facts come back and at what quantity, and optionally the corrected amounts that replace them. What comes out is the JURISDICTION's shape and not the caller's - under a separate-document law a credit note plus, where corrected amounts were stated, a replacement invoice; under a single-document law one corrective carrying both. The reversing money is the original's money taken back proportionally, carrying its tax rate and FX pin, so there is no second apportionment. The credit is spent at once: what the original still owes is taken off it, and what is left - money the customer already paid - is returned to their wallet in the document's currency, as a ledger entry naming the credit note (credit_destination = wallet) that the wallet spends on their next invoice. There is nothing left on the note to apply by hand. Correcting twice with the same request returns the first correction rather than minting a second. The answer names each document by id (original_id, correction_id, replacement_id); include=original, correction and replacement embed the documents themselves. All three are sent without being asked until 2026-11-30; after that only when named.
Required scope: credit_note.issue (Issue credit notes).
query Parameters
includeExtra data to add to the response: tags, original, correction, replacement. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. tags is sent without being asked until 2026-11-30; after that date it is sent only when named here. original is sent without being asked until 2026-11-30; after that date it is sent only when named here. correction is sent without being asked until 2026-11-30; after that date it is sent only when named here. replacement is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
Idempotency-KeyIdempotency key threaded into the correction as its dedup token
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Correct an issued invoice › Request Body
original_document_idThe issued document being restated. Required: this operation corrects one document and the path names none.
The atoms to take back and how much of each. An empty list with new entries is a goodwill credit; the whole document is taken back by the reverse operation instead.
Corrected amounts. Under the separate shape they become a replacement invoice; under the single shape they are positive atoms on the corrective itself.
policyThe shape asked for. Read ONLY where the jurisdiction's own law admits both; everywhere else the law decides and this is ignored, because the shape of a legal document is not an operator preference.
reasonWhy the document is being restated: a closed set, persisted on the correcting document (several jurisdictions require the why on it). Empty means OTHER.
Requests also accept the new spelling: each value in lower case (billing_error for BILLING_ERROR). The listed spelling is deprecated in requests and accepted until 2026-11-30.
Correct an issued invoice › Responses
Created
Get a credit note
Returns one crediting document, with the include values of GET /invoices/{id} (lines, lines.atoms, lines.atoms.tax_rule, inputs). Its money is negative, because its atoms are: a reversing atom carries the original's unit price and negates the quantity, so the header identity holds for a credit note exactly as it does for an invoice. An id that names an invoice is refused rather than served, because the path says which kind is being asked for. Until 2026-11-30 this read sends the lines and, on a draft, the inputs without being asked; after that only when named.
Required scope: credit_note.read (Read credit notes).
path Parameters
idDocument UUID
query Parameters
includeExtra data to add to the response: tags, lines, lines.atoms, lines.atoms.tax_rule, inputs. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. tags is sent without being asked until 2026-11-30; after that date it is sent only when named here. lines is sent without being asked until 2026-11-30; after that date it is sent only when named here. inputs is sent without being asked until 2026-11-30; after that date it is sent only when named here.
atomsAdds the atoms under each line and again as the top-level atoms list; include=lines.atoms adds them under their lines only. Deprecated: use include=lines.atoms instead. Removed on 2026-11-30.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a credit note › Responses
OK
Discard a draft credit note
Throws a draft crediting document away; the answer is the document in status discarded. An issued one cannot be discarded - it was sent, and the way back is to reverse it, which mints a document recording that the credit was taken back. The same discard as DELETE /invoices/{id}.
Required scope: credit_note.issue (Issue credit notes).
path Parameters
idDocument UUID
query Parameters
includeExtra data to add to the response: tags, lines, lines.atoms, lines.atoms.tax_rule, inputs. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. tags is sent without being asked until 2026-11-30; after that date it is sent only when named here.
reasonWhy the draft is being discarded.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Discard a draft credit note › Responses
OK
List credit note applications
Every document this credit has been applied to, with the per-application amount.
Required scope: credit_note.read (Read credit notes).
path Parameters
idDocument UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List credit note applications › Responses
OK
Finalize a credit note
Finalizes a draft crediting document: freezes its lines, stamps it and mints its number from the credit-note series. It is the same finalize an invoice takes (POST /invoices/{id}/finalize), because a credit note is an invoice in EN 16931's sense. Once finalized, its lines and figures are immutable.
Required scope: credit_note.issue (Issue credit notes).
path Parameters
idDocument UUID
query Parameters
includeExtra data to add to the response: tags, lines, lines.atoms, lines.atoms.tax_rule, inputs. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. tags is sent without being asked until 2026-11-30; after that date it is sent only when named here. lines is sent without being asked until 2026-11-30; after that date it is sent only when named here. lines.atoms is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Finalize a credit note › Responses
OK
Issue a credit note
Deprecated: use POST /credit-notes/{id}/finalize instead. Removed on 2026-11-30.
Finalizes a draft crediting document, as POST /credit-notes/{id}/finalize does. Use that operation: this path is removed on 2026-11-30.
Required scope: credit_note.issue (Issue credit notes).
path Parameters
idDocument UUID
query Parameters
includeExtra data to add to the response: tags, lines, lines.atoms, lines.atoms.tax_rule, inputs. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. tags is sent without being asked until 2026-11-30; after that date it is sent only when named here. lines is sent without being asked until 2026-11-30; after that date it is sent only when named here. lines.atoms is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Issue a credit note › Responses
OK
Download credit-note PDF
Streams the credit-note PDF, which is the visual document and distinct from the XRechnung XML. A draft is refused.
Required scope: credit_note.read (Read credit notes).
path Parameters
idDocument UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Download credit-note PDF › Responses
PDF file
Regenerate a document's artifact
Asks the document worker to draw the artifact again. Idempotent: two submissions enqueue two jobs and the archive's content-hash dedup keeps the second from writing.
Required scope: credit_note.issue (Issue credit notes).
path Parameters
idDocument UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Regenerate a document's artifact › Responses
Accepted
Add tags to a credit-note
Adds the given tags to the credit-note and keeps the tags it already has. Returns all tags on the credit-note after the change. The credit-note itself lists them in tag_ids, and in tags with include=tags.
Required scope: tag.write (Manage tags).
path Parameters
idResource UUID
query Parameters
includeExtra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Add tags to a credit-note › Request Body
tag_idsThe tags to add. Each must be a tag for this kind of record.
Add tags to a credit-note › Responses
OK
Remove tags from a credit-note
Removes the tags given in the tag_ids query parameter from the credit-note in one call. Its other tags stay; an id it does not carry is ignored.
Required scope: tag.write (Manage tags).
path Parameters
idResource UUID
query Parameters
tag_idsTag UUIDs to remove
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Remove tags from a credit-note › Responses
No Content
Discard a draft credit note
Deprecated: use DELETE /credit-notes/{id} instead. Removed on 2026-11-30.
Throws a draft crediting document away, as DELETE /credit-notes/{id} does. Here void means discard, while POST /invoices/{id}/void reverses an issued invoice: use DELETE /credit-notes/{id}. This path is removed on 2026-11-30.
Required scope: credit_note.issue (Issue credit notes).
path Parameters
idDocument UUID
query Parameters
includeExtra data to add to the response: tags, lines, lines.atoms, lines.atoms.tax_rule, inputs. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. tags is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Discard a draft credit note › Request Body
reasonWhy the draft is being discarded.
Discard a draft credit note › Responses
OK
Download XRechnung XML for a credit note
Streams the EN 16931-compliant credit-note e-invoice artifact. Only an issued document has one; a draft is refused, because the artifact prints a number a draft does not carry.
Required scope: credit_note.read (Read credit notes).
path Parameters
idDocument UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Download XRechnung XML for a credit note › Responses
E-invoice artifact (CII XML or hybrid PDF/A-3)