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
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
countsComma-separated countable fields (status, reason_code) to include per-value counts for
sortOrdering: created_at, status, credit_note_number, reason_code, total, amount_remaining or issued_at, each with an optional :asc/:desc suffix (default created_at:desc). An unknown value is rejected. total and amount_remaining order by currency first, then the amount within it - an amount across currencies is not a quantity. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
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).
Credit-note line items; at least one is required.
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.
fx_snapshot_base_leg_idFor a triangulated cross-pair invoice rate, the EUR→source FX snapshot it was divided by; populated by refund builders.
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.
Arbitrary caller-supplied key/value pairs.
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
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
Record the buyer's acknowledgement of a credit note
Portugal (art. 78.º n.º 5 CIVA): records the proof that the buyer knew of the correction, or was refunded the tax. Until it is on file, regularising the IVA in the supplier's favour is «indevida» — the note itself is unaffected and stays issued. Write-once: the date starts a statutory period and the kind is a claim about what evidence is held, so neither may be rewritten. Refused for a credit note governed by any other jurisdiction's law.
path Parameters
idCredit 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.
Record the buyer's acknowledgement of a credit note › Request Body
acknowledged_atWhen the proof came into your possession (not when it was recorded here).
kindWhat the proof is. The closed set the Autoridade Tributária admits (Ofício-Circulado 33129/1993, confirmed in AT ruling 23501/2023): a written communication from the customer referring to the IVA correction, a signed or stamped copy of the note, an EDI acknowledgement, or proof the buyer was refunded the tax. A bare read receipt is NOT among them.
evidenceA reference to the proof itself: a message id, a document reference, a note of where the signed copy is filed. The artefact lives outside this system; this is the pointer an inspection follows.
Record the buyer's acknowledgement of 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
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
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+)?$ · requiredMAJOR units, in the addressed credit note's currency.
invoice_idInvoice to apply the credit against, or refund from (required).
currencyOptional echo-guard: must equal the credit note's currency when set.
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
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
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
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
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
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
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