Credit notes: drafts, issuing, application against invoices, cash refunds, and PDF/XRechnung artifacts.
List credit notes
Returns a paginated list of credit notes. Filters use the unified field.op=value grammar.
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.
credit_note_numberFilter on credit_note_number (string). Operators: eq, in, contains — dot grammar, e.g. credit_note_number.in=value; a bare credit_note_number=value means eq. A bare comma-separated value is in-sugar: credit_note_number=a,b means credit_note_number.in=a,b.
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.
invoice_idFilter on invoice_id (uuid). Operators: eq, in — dot grammar, e.g. invoice_id.in=value; a bare invoice_id=value means eq. A bare comma-separated value is in-sugar: invoice_id=a,b means invoice_id.in=a,b.
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.
reason_codeFilter on reason_code (enum). Operators: eq, in — dot grammar, e.g. reason_code.in=value; a bare reason_code=value means eq. A bare comma-separated value is in-sugar: reason_code=a,b means reason_code.in=a,b. Legal values: VOID, REFUND, PROMOTIONAL_CREDIT, CANCELLATION, WITHDRAWAL, DOWNGRADE, ITEM_REMOVAL, OVERPAYMENT, BILLING_ERROR, GOODWILL, OTHER.
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.
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 credit_note_number
Case-insensitive substring match over credit_note_number
statusFilter by status. Filterable fields (status, customer_id, invoice_id, currency, credit_note_number, reason_code, issued_at, created_at, updated_at) accept apifilter operator suffixes in the dot grammar, e.g. status.in=a,b
Filter by status. Filterable fields (status, customer_id, invoice_id, currency, credit_note_number, reason_code, issued_at, created_at, updated_at) accept apifilter operator suffixes in the dot grammar, e.g. status.in=a,b
countsComma-separated countable fields (status, reason_code) to include per-value counts for
Comma-separated countable fields (status, reason_code) 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
Create a credit note
Creates a credit note in draft status - it is not yet posted to the customer ledger. The credit_note_number is allocated at issue time.
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.
Create a credit note › Request Body
currencyISO 4217 currency for the note and all its lines (required).
customer_idCustomer to issue the credit note to (required).
fx_snapshot_idFX snapshot to pin the note to (the original invoice's rate); populated by refund builders, rarely set by API callers.
invoice_idInvoice this note reverses or credits; omit for a standalone customer credit.
Credit-note line items; at least one is required.
Arbitrary caller-supplied key/value pairs.
reasonFree-text reason shown on the document.
reason_codeStructured reason: VOID, REFUND, PROMOTIONAL_CREDIT, CANCELLATION, WITHDRAWAL, DOWNGRADE, ITEM_REMOVAL, OVERPAYMENT, BILLING_ERROR, GOODWILL, or OTHER.
template_idTemplate to render the note's document with; omit to inherit the org default.
Create a credit note › Responses
Created
Get a credit note
Returns a single credit note by UUID, including its line items.
path Parameters
idCredit note UUID
Credit note 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.
Get a credit note › Responses
OK
List credit note applications
Every application of this credit note - invoices it was applied against and refunds issued from it, with the per-application amount.
path Parameters
idCredit note UUID
Credit note 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
Apply a credit note
Applies a portion (or all) of the credit note's remaining balance - either against an open invoice or as a cash refund. Records a credit_note_application row.
path Parameters
idCredit note UUID
Credit note 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.
Apply a credit note › Request Body
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed credit note's currency.
currencyOptional echo-guard: must equal the credit note's currency when set.
invoice_idInvoice to apply the credit against, or refund from (required).
Apply a credit note › Responses
Created
Issue a credit note
Finalizes a draft credit note: allocates the credit_note_number, posts it to the customer ledger, and emits the issued event. Once issued, line items and totals are immutable.
path Parameters
idCredit note UUID
Credit note 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.
Issue a credit note › Responses
OK
Download credit-note PDF
Streams the credit-note PDF (visual layout, distinct from the XRechnung XML). Drafts are rejected.
path Parameters
idCredit note UUID
Credit note 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 credit-note PDF
Re-queues a document.requested event so the document worker re-renders and archives the PDF. Idempotent via the archive's content-hash dedup. Responds 202.
path Parameters
idCredit note UUID
Credit note 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 credit-note PDF › Responses
Accepted
Void a credit note
Marks the credit note as void. A draft is voided in place; an issued credit note is voided only if it has no applications.
path Parameters
idCredit note UUID
Credit note 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.
Void a credit note › Responses
OK
Download XRechnung XML for a credit note
Streams the EN 16931-compliant credit-note e-invoice artifact. Only valid for issued / partially_applied / applied credit notes - drafts return 409.
path Parameters
idCredit note UUID
Credit note 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)
Get customer credit balance
The customer's available credit balance, broken down by currency. Sums the unapplied portion of every issued, non-voided credit note for the customer.
path Parameters
idCustomer UUID
Customer 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.
Get customer credit balance › Responses
OK