An invoice is a formal request for payment sent to a customer. Invoices are generated automatically at the end of each billing period, or manually for one-off charges, credits, and adjustments.
The invoice lifecycle is: draft → finalized → sent → paid (or void / uncollectible). Draft invoices can be edited; finalized invoices are immutable and receive a sequential invoice number.
Key concepts:
- Invoice type -
subscription(recurring),one_off(manual), orcredit_note(refund/adjustment) - Line items - individual charges with product, quantity, amount, and tax breakdown
- Credit notes - partial or full reversals of a finalized invoice
- PDF export - generate a formatted PDF for download or email delivery
- XRechnung - EU-compliant electronic invoice format (XML) for B2G billing
- Buyer reference - PO number or reference that appears on the invoice for the customer's records
List invoices
Lists billing documents with cursor-based pagination and the unified field.op=value filter grammar (status, kind, customer_id, subscription_id, original_document_id, origin, currency, number, created_at, updated_at, due_date, issued_at, paid_at, partially_paid). It defaults to kind=invoice, so the invoice list stays the invoice list; state a kind filter to widen it. Statuses are draft, finalized, overdue, paid, reversed, uncollectible and discarded.
Required scope: invoice.read (Read invoices).
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 invoices › Responses
OK
Create a draft invoice
Creates a draft. With subscription_id and a period it is assembled from the subscription and adopts the accrued charges already waiting for that window; a period that already carries a live document is refused unless replace_draft says to replace the draft standing in it. With customer_id and currency it is a standalone draft attached to no subscription. Optional entries are applied inline, and the supply date, buyer reference and metadata are written with the draft. A standalone draft stating no period bills the supply day: delivery_date, else today. The number is minted at finalize. A draft that cannot be assembled is refused with every reason in the problem document's refusals.
Required scope: invoice.write (Write invoices).
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.
Create a draft invoice › Request Body
buyer_referenceBuyer's routing reference (Leitweg-ID / PO number) for B2G and e-invoicing (BT-10).
currencyISO 4217 currency. Required for a manual document; a subscription supplies its own.
customer_idThe customer to bill. Required for a manual document, and inferred from the subscription otherwise.
delivery_dateDate of supply (BT-72, Leistungsdatum §14 UStG). A manual document stating no period bills this day, so it is also the date its tax rate is read at.
due_datePayment due date. Omitted, it is resolved from the payment-terms ladder at finalize.
Manual inputs stated at draft time, for a caller that has them in hand. An operator adds them one at a time instead.
localeRendering locale; null inherits the org default.
The caller's own key/value pairs, e.g. an external system's ids. At most 50 keys, each at most 40 characters; a value is at most 500 bytes as JSON. The keys supplier_iban, supplier_bic, payment_terms, supplier_register_court, supplier_register_number, refund_iban and refund_method are refused: they are the organization's legal facts, set in its profile. A template binding invoice.metadata.
period_endEnd instant of that period, exclusive.
period_startStart instant of the period to bill. The window arrives already anchored; assembly computes no anchor. A manual document stating neither period_start nor period_end bills the supply day: delivery_date, else today.
replace_draftAdmit replacing an existing DRAFT for the same subscription period. Without it a taken period is refused, and an ISSUED document is refused either way.
subscription_idThe subscription to bill. Its deal atoms are assembled for the period.
Create a draft invoice › Responses
Created
Draft an invoice from a subscription
Deprecated: use POST /invoices instead. Removed on 2026-11-30.
Assembles a draft from a subscription for a billing period and adopts the accrued charges already waiting for that window. A period that already carries a live document is refused unless replace_draft says to replace the draft standing in it.
Required scope: invoice.write (Write invoices).
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.
Draft an invoice from a subscription › Request Body
buyer_referenceBuyer's routing reference (Leitweg-ID / PO number) for B2G and e-invoicing (BT-10).
currencyISO 4217 currency. Required for a manual document; a subscription supplies its own.
customer_idThe customer to bill. Required for a manual document, and inferred from the subscription otherwise.
delivery_dateDate of supply (BT-72, Leistungsdatum §14 UStG). A manual document stating no period bills this day, so it is also the date its tax rate is read at.
due_datePayment due date. Omitted, it is resolved from the payment-terms ladder at finalize.
Manual inputs stated at draft time, for a caller that has them in hand. An operator adds them one at a time instead.
localeRendering locale; null inherits the org default.
The caller's own key/value pairs, e.g. an external system's ids. At most 50 keys, each at most 40 characters; a value is at most 500 bytes as JSON. The keys supplier_iban, supplier_bic, payment_terms, supplier_register_court, supplier_register_number, refund_iban and refund_method are refused: they are the organization's legal facts, set in its profile. A template binding invoice.metadata.
period_endEnd instant of that period, exclusive.
period_startStart instant of the period to bill. The window arrives already anchored; assembly computes no anchor. A manual document stating neither period_start nor period_end bills the supply day: delivery_date, else today.
replace_draftAdmit replacing an existing DRAFT for the same subscription period. Without it a taken period is refused, and an ISSUED document is refused either way.
subscription_idThe subscription to bill. Its deal atoms are assembled for the period.
Draft an invoice from a subscription › Responses
Created
Preview an invoice
Assembles the document a subscription would produce for a period and persists nothing. It is the SAME assembly the draft runs, which is the point: a preview that priced differently from the draft showed the customer a number they were not billed. Until 2026-11-30 the answer sends the lines with their atoms without being asked, and the atoms a second time as the deprecated top-level list; after that only what include names.
Required scope: invoice.read (Read invoices).
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
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.
Preview an invoice › Request Body
buyer_referenceBuyer's routing reference (Leitweg-ID / PO number) for B2G and e-invoicing (BT-10).
currencyISO 4217 currency. Required for a manual document; a subscription supplies its own.
customer_idThe customer to bill. Required for a manual document, and inferred from the subscription otherwise.
delivery_dateDate of supply (BT-72, Leistungsdatum §14 UStG). A manual document stating no period bills this day, so it is also the date its tax rate is read at.
due_datePayment due date. Omitted, it is resolved from the payment-terms ladder at finalize.
Manual inputs stated at draft time, for a caller that has them in hand. An operator adds them one at a time instead.
localeRendering locale; null inherits the org default.
The caller's own key/value pairs, e.g. an external system's ids. At most 50 keys, each at most 40 characters; a value is at most 500 bytes as JSON. The keys supplier_iban, supplier_bic, payment_terms, supplier_register_court, supplier_register_number, refund_iban and refund_method are refused: they are the organization's legal facts, set in its profile. A template binding invoice.metadata.
period_endEnd instant of that period, exclusive.
period_startStart instant of the period to bill. The window arrives already anchored; assembly computes no anchor. A manual document stating neither period_start nor period_end bills the supply day: delivery_date, else today.
replace_draftAdmit replacing an existing DRAFT for the same subscription period. Without it a taken period is refused, and an ISSUED document is refused either way.
subscription_idThe subscription to bill. Its deal atoms are assembled for the period.
Preview an invoice › Responses
OK
Get an invoice
Returns one billing document. include=lines adds its presented lines; include=lines.atoms adds the atoms (the priced facts a replay, a correction and a dispute are settled on) under each line, and include=lines.atoms.tax_rule names the tax rule of each atom; include=inputs adds the stored entries and overrides an edit of a draft addresses. Every operation that answers an invoice takes the same include values. 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: invoice.read (Read invoices).
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 an invoice › Responses
OK
Discard a draft invoice
Throws a draft away and releases what it was holding: the accrued charges it adopted go back to waiting, the promotional holds it took are given up and the allowance units it reserved go back to their lots, so the period is billable again. The answer is the document in status discarded: it stays readable, without a number. Legal for a draft alone - an issued document is reversed (POST /invoices/{id}/void) or corrected (POST /credit-notes), because it has been sent.
Required scope: invoice.write (Write invoices).
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 invoice › Responses
OK
Update header fields on a draft invoice
Edits the header's own facts: due date, delivery date, locale, buyer reference and metadata. It re-runs no assembly, because none of them moves money. The due date is the one field that may still change after issue; the others need a draft. Status, currency, customer, kind and every figure are immutable through this path - the currency is an input to assembly, the figures are a sum over atoms, and the status has exactly one writer.
Required scope: invoice.write (Write invoices).
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. inputs is sent without being asked until 2026-11-30; after that date it is sent only when named here.
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.
Update header fields on a draft invoice › Request Body
buyer_referenceBuyer's routing reference (Leitweg-ID / PO number); null clears it, omitted leaves it. Draft only.
delivery_dateDate of supply (BT-72); null clears it, omitted leaves it. Draft only.
due_datePayment due date; null clears it, omitted leaves it. The ONE header field that may still change after issue, because a renegotiated payment term is a commercial decision and not a restatement of the supply.
localeRendering locale; null clears it so the organization's default applies, omitted leaves it. Draft only.
The caller's own key/value pairs; an object REPLACES the whole map, null clears it, omitted leaves it. Draft only. At most 50 keys, each at most 40 characters; a value is at most 500 bytes as JSON. The keys supplier_iban, supplier_bic, payment_terms, supplier_register_court, supplier_register_number, refund_iban and refund_method are refused: they are the organization's legal facts, set in its profile. A template binding invoice.metadata.
Update header fields on a draft invoice › Responses
OK
List the document's priced facts
The atoms: one per product, key and segment, each carrying the pins a replay needs — product version, price, plan price, negotiated override, tax rule version, FX snapshot, tier steps and formula or rate versions — plus what it drew from an allowance or a credit grant. This is what an audit, a replay and a dispute are settled on. include=tax_rule names the tax rule each atom's tax_rule_version_id is a version of.
Required scope: invoice.read (Read invoices).
path Parameters
idDocument UUID
query Parameters
includeExtra data to add to the response: tax_rule. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
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 the document's priced facts › Responses
OK
Charge an invoice now
Charges the customer's saved auto-pay method off-session, right now, through the same collector every automatic door uses, and reports the outcome: charged (the provider webhook settles the document), declined (with the provider's reason; the decline is recorded against the document, and the retry steps of its dunning policy, if the policy has any, charge the saved method again on their days), checkout_required (no saved method; send the customer to checkout_url, a hosted page of the provider that pays this balance once and returns the customer to the portal's checkout page; it saves no method for later charges, which the portal's add-payment-method page does), no_payment_method (no saved method, and the provider has no hosted flow or the deployment has no portal to return the customer to), awaiting_sepa_file (the customer pays by a SEPA mandate the seller collects with its own SEPA files: nothing is charged now, the next file collects the document), or awaiting_sepa_prenotice (the customer pays by a SEPA mandate on a payment provider: the debit must be announced first, so the pre-notification was sent and the charge runs on the day it names). To learn when a customer saves a method without polling, subscribe to the payment_method.attached webhook.
Required scope: invoice.write (Write invoices).
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.
Charge an invoice now › Responses
OK
List credit applications against an invoice
Every credit application that has reduced this document's amount due, with a total_credited / remaining_creditable summary. The summary is summed over the applications themselves: they ARE what has been credited, and a stored total beside them would be a second statement of the same money.
Required scope: invoice.read (Read invoices).
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 applications against an invoice › Responses
OK
Credit applications that have reduced this document's amount due.
Pagination block; this collection is returned unpaginated with a total count.
Document-level credit rollup.
Discard a draft invoice
Deprecated: use DELETE /invoices/{id} instead. Removed on 2026-11-30.
Throws a draft away, as DELETE /invoices/{id} does. Use that operation: this path is removed on 2026-11-30.
Required scope: invoice.write (Write invoices).
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 invoice › Request Body
reasonWhy the draft is being discarded.
Discard a draft invoice › Responses
OK
Add a manual charge to a draft invoice
Stores one entry (a manual charge) on a draft and re-derives the lines. A line is not what is stored: it is a bucket of atoms under the presentation policy, so the entry is the durable fact and the line it lands in may be shared with the deal's own charges for the same product and key. The answer is the whole document, because one entry can change the tax apportionment of every line; the new entry is the last of its entries (include=inputs).
Required scope: invoice.write (Write invoices).
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. inputs 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.
Add a manual charge to a draft invoice › Request Body
quantity^-?\d+(\.\d+)?$ · requiredQuantity, as a decimal string.
period_endperiod_startSpan this entry bills; defaults to the document's period.
price_basisWhether unit_price is a net taxable base (exclusive, the default) or an amount the tax is already inside (inclusive). Under inclusive the document states a base and a tax that add up to the stated figure exactly. It qualifies a stated unit_price only: an entry left to the catalog bills on the catalog price's basis.
price_keyPrice component to name.
product_idThe catalog product to price against. Omitted, the entry must carry a title, and it is taxed under the document's own determination unless it declares a tax category.
tax_category_codeEN 16931 tax category code (BT-151). Declared, it states the entry's treatment; omitted, the entry takes the document's own determination, as a product of the default tax category does.
tax_rate^-?\d+(\.\d+)?$A rate the entry states itself, as a fraction (0.13 = 13%). Stated, it is the line's rate and the jurisdiction's rules are not asked; the category is then S unless tax_category_code says otherwise. Omitted, the rate is determined. A positive rate under a category other than S, or a zero rate under S or no category, is refused (TAX_RATE_CONTRADICTS_CATEGORY); a rate below 0, of 1 or more, or finer than six decimals is refused (TAX_RATE_INVALID); S stated on a document whose supply is zero-rated is refused (TAX_CATEGORY_CONTRADICTS_DOCUMENT). A correction's new_entries may state only a rate the original billed.
titleThe entry's heading. Required when the entry names no product.
unit_labelWhat one unit is called, for display. Omitted, the line shows the bare quantity.
unit_price^-?\d+(\.\d+)?$Price per unit in MAJOR units of the document's currency. Stated, it wins. Omitted, the entry is priced from its product's catalog: the published price in force at the entry's start (period_start, else the document's), for this quantity, never the plan price or a rate the subscription negotiated. It is resolved whenever the draft is assembled (creation and every edit) and finalize keeps it. Omitting it requires product_id (ENTRY_PRICE_MISSING otherwise) and bills on the catalog price's own basis, whatever price_basis says; a correction's new_entries must state it.
Add a manual charge to a draft invoice › Responses
Created
Remove a manual charge from a draft invoice
Withdraws one stored entry and re-derives the lines.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument UUID
entry_idEntry 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.
Remove a manual charge from a draft invoice › Responses
No Content
Update a manual charge on a draft invoice
Replaces one stored entry in full and re-derives the lines: a field left out is cleared. To change a charge the deal produced - a quantity a meter reported, a price the catalog answered - override its atom (POST /invoices/{id}/overrides): there is no entry behind those.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument UUID
entry_idEntry 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. inputs is sent without being asked until 2026-11-30; after that date it is sent only when named here.
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.
Update a manual charge on a draft invoice › Request Body
quantity^-?\d+(\.\d+)?$ · requiredQuantity, as a decimal string.
period_endperiod_startSpan this entry bills; defaults to the document's period.
price_basisWhether unit_price is a net taxable base (exclusive, the default) or an amount the tax is already inside (inclusive). Under inclusive the document states a base and a tax that add up to the stated figure exactly. It qualifies a stated unit_price only: an entry left to the catalog bills on the catalog price's basis.
price_keyPrice component to name.
product_idThe catalog product to price against. Omitted, the entry must carry a title, and it is taxed under the document's own determination unless it declares a tax category.
tax_category_codeEN 16931 tax category code (BT-151). Declared, it states the entry's treatment; omitted, the entry takes the document's own determination, as a product of the default tax category does.
tax_rate^-?\d+(\.\d+)?$A rate the entry states itself, as a fraction (0.13 = 13%). Stated, it is the line's rate and the jurisdiction's rules are not asked; the category is then S unless tax_category_code says otherwise. Omitted, the rate is determined. A positive rate under a category other than S, or a zero rate under S or no category, is refused (TAX_RATE_CONTRADICTS_CATEGORY); a rate below 0, of 1 or more, or finer than six decimals is refused (TAX_RATE_INVALID); S stated on a document whose supply is zero-rated is refused (TAX_CATEGORY_CONTRADICTS_DOCUMENT). A correction's new_entries may state only a rate the original billed.
titleThe entry's heading. Required when the entry names no product.
unit_labelWhat one unit is called, for display. Omitted, the line shows the bare quantity.
unit_price^-?\d+(\.\d+)?$Price per unit in MAJOR units of the document's currency. Stated, it wins. Omitted, the entry is priced from its product's catalog: the published price in force at the entry's start (period_start, else the document's), for this quantity, never the plan price or a rate the subscription negotiated. It is resolved whenever the draft is assembled (creation and every edit) and finalize keeps it. Omitting it requires product_id (ENTRY_PRICE_MISSING otherwise) and bills on the catalog price's own basis, whatever price_basis says; a correction's new_entries must state it.
Update a manual charge on a draft invoice › Responses
OK
Finalize an invoice
Freezes the presentation, stamps the document's identity, governing law, tax currency and duties, mints its number and queues its rendering - in one transaction. Once finalized the document is immutable except its settlement, its dunning cursor and its status.
Required scope: invoice.finalize (Finalize invoices).
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 an invoice › Responses
OK
List invoice lines
Returns the document's presented lines whole, with a total count. They are not paginated: a line is a projection of atoms under the presentation policy, so the count is the number of buckets the policy produced and is bounded by the deal's products and keys. include=atoms adds the atoms under each line and include=atoms.tax_rule names the tax rule of each. Each line carries structured fields — title, key label, unit, period, quantities, unit price, tax — and never a composed sentence.
Required scope: invoice.read (Read invoices).
path Parameters
idDocument UUID
query Parameters
includeExtra data to add to the response: atoms, atoms.tax_rule. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
atomsAdds the atoms under each line. Deprecated: use include=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.
List invoice lines › Responses
OK
Add a manual charge to a draft invoice
Deprecated: use POST /invoices/{id}/entries instead. Removed on 2026-11-30.
Stores one entry on a draft, as POST /invoices/{id}/entries does. Use that operation: this path is removed on 2026-11-30.
Required scope: invoice.write (Write invoices).
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. inputs 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.
Add a manual charge to a draft invoice › Request Body
quantity^-?\d+(\.\d+)?$ · requiredQuantity, as a decimal string.
period_endperiod_startSpan this entry bills; defaults to the document's period.
price_basisWhether unit_price is a net taxable base (exclusive, the default) or an amount the tax is already inside (inclusive). Under inclusive the document states a base and a tax that add up to the stated figure exactly. It qualifies a stated unit_price only: an entry left to the catalog bills on the catalog price's basis.
price_keyPrice component to name.
product_idThe catalog product to price against. Omitted, the entry must carry a title, and it is taxed under the document's own determination unless it declares a tax category.
tax_category_codeEN 16931 tax category code (BT-151). Declared, it states the entry's treatment; omitted, the entry takes the document's own determination, as a product of the default tax category does.
tax_rate^-?\d+(\.\d+)?$A rate the entry states itself, as a fraction (0.13 = 13%). Stated, it is the line's rate and the jurisdiction's rules are not asked; the category is then S unless tax_category_code says otherwise. Omitted, the rate is determined. A positive rate under a category other than S, or a zero rate under S or no category, is refused (TAX_RATE_CONTRADICTS_CATEGORY); a rate below 0, of 1 or more, or finer than six decimals is refused (TAX_RATE_INVALID); S stated on a document whose supply is zero-rated is refused (TAX_CATEGORY_CONTRADICTS_DOCUMENT). A correction's new_entries may state only a rate the original billed.
titleThe entry's heading. Required when the entry names no product.
unit_labelWhat one unit is called, for display. Omitted, the line shows the bare quantity.
unit_price^-?\d+(\.\d+)?$Price per unit in MAJOR units of the document's currency. Stated, it wins. Omitted, the entry is priced from its product's catalog: the published price in force at the entry's start (period_start, else the document's), for this quantity, never the plan price or a rate the subscription negotiated. It is resolved whenever the draft is assembled (creation and every edit) and finalize keeps it. Omitting it requires product_id (ENTRY_PRICE_MISSING otherwise) and bills on the catalog price's own basis, whatever price_basis says; a correction's new_entries must state it.
Add a manual charge to a draft invoice › Responses
Created
Remove a manual charge from a draft invoice
Deprecated: use DELETE /invoices/{id}/entries/{entry_id} instead. Removed on 2026-11-30.
Withdraws one stored entry, as DELETE /invoices/{id}/entries/{entry_id} does; the path id is the entry's. Use that operation: this path is removed on 2026-11-30.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument UUID
lineIdEntry 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.
Remove a manual charge from a draft invoice › Responses
No Content
Update a manual charge on a draft invoice
Deprecated: use PATCH /invoices/{id}/entries/{entry_id} instead. Removed on 2026-11-30.
Replaces one stored entry, as PATCH /invoices/{id}/entries/{entry_id} does; the path id is the entry's. Use that operation: this path is removed on 2026-11-30.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument UUID
lineIdEntry UUID. The path segment is named lineId for the release this rework lands in; the id it carries is the ENTRY's, because an entry is what an edit addresses.
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. inputs is sent without being asked until 2026-11-30; after that date it is sent only when named here.
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.
Update a manual charge on a draft invoice › Request Body
quantity^-?\d+(\.\d+)?$ · requiredQuantity, as a decimal string.
period_endperiod_startSpan this entry bills; defaults to the document's period.
price_basisWhether unit_price is a net taxable base (exclusive, the default) or an amount the tax is already inside (inclusive). Under inclusive the document states a base and a tax that add up to the stated figure exactly. It qualifies a stated unit_price only: an entry left to the catalog bills on the catalog price's basis.
price_keyPrice component to name.
product_idThe catalog product to price against. Omitted, the entry must carry a title, and it is taxed under the document's own determination unless it declares a tax category.
tax_category_codeEN 16931 tax category code (BT-151). Declared, it states the entry's treatment; omitted, the entry takes the document's own determination, as a product of the default tax category does.
tax_rate^-?\d+(\.\d+)?$A rate the entry states itself, as a fraction (0.13 = 13%). Stated, it is the line's rate and the jurisdiction's rules are not asked; the category is then S unless tax_category_code says otherwise. Omitted, the rate is determined. A positive rate under a category other than S, or a zero rate under S or no category, is refused (TAX_RATE_CONTRADICTS_CATEGORY); a rate below 0, of 1 or more, or finer than six decimals is refused (TAX_RATE_INVALID); S stated on a document whose supply is zero-rated is refused (TAX_CATEGORY_CONTRADICTS_DOCUMENT). A correction's new_entries may state only a rate the original billed.
titleThe entry's heading. Required when the entry names no product.
unit_labelWhat one unit is called, for display. Omitted, the line shows the bare quantity.
unit_price^-?\d+(\.\d+)?$Price per unit in MAJOR units of the document's currency. Stated, it wins. Omitted, the entry is priced from its product's catalog: the published price in force at the entry's start (period_start, else the document's), for this quantity, never the plan price or a rate the subscription negotiated. It is resolved whenever the draft is assembled (creation and every edit) and finalize keeps it. Omitting it requires product_id (ENTRY_PRICE_MISSING otherwise) and bills on the catalog price's own basis, whatever price_basis says; a correction's new_entries must state it.
Update a manual charge on a draft invoice › Responses
OK
Override a quantity, unit price or heading on a draft
Replaces one field of one priced fact and re-derives the projection. This is how an operator corrects what the deal produced: the replacement is STORED as an input, never patched onto a line, because a line is derived and a patched projection is a second definition of the money. The atom id survives the re-assembly it triggers, because assembly mints it from its inputs.
Required scope: invoice.write (Write invoices).
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. inputs 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.
Override a quantity, unit price or heading on a draft › Request Body
fieldWhich field to replace.
target_idThe atom to override.
valueThe replacement, as text: a decimal for quantity and unit_price, the heading for title.
Override a quantity, unit price or heading on a draft › Responses
Created
Withdraw an override
Withdraws one stored replacement, named by its id (the document's overrides, include=inputs); the field goes back to what assembly answers. The answer is the re-derived document.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument UUID
override_idOverride UUID: the id of an entry of the document's overrides (include=inputs).
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. inputs is sent without being asked until 2026-11-30; after that date it is sent only when named here.
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.
Withdraw an override › Responses
OK
Withdraw an override
Deprecated: use DELETE /invoices/{id}/overrides/{override_id} instead. Removed on 2026-11-30.
Withdraws one stored replacement, named by the atom and the field it replaces, as DELETE /invoices/{id}/overrides/{override_id} does by the override's own id. Use that operation: this path is removed on 2026-11-30.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument UUID
targetIdThe atom whose override is withdrawn.
fieldWhich replaced field to withdraw.
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. inputs is sent without being asked until 2026-11-30; after that date it is sent only when named here.
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.
Withdraw an override › Responses
OK
List payments recorded against an invoice
The document's full payment timeline - gateway payments in any lifecycle state merged with operator-recorded ones, newest first.
Required scope: invoice.read (Read invoices).
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 payments recorded against an invoice › Responses
OK
Download invoice PDF
Streams the canonical PDF. Within the post-finalize grace window a missing artifact responds 409 with Retry-After while the document worker renders it.
Required scope: invoice.read (Read invoices).
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 invoice PDF › Responses
PDF file
Record a payment on an invoice
Settles money against a finalized or overdue document. One path for every rail: an operator's hand-entered receipt and a provider's report are the same operation with a different provider and reference. A replayed report is recognised by the (document, provider, reference) claim and answered with the document unchanged rather than refused as an overpayment.
Required scope: invoice.write (Write invoices).
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.
Record a payment on an invoice › Request Body
What arrived, {value, currency}: a positive amount in the document's currency. Another currency is refused with CURRENCY_MISMATCH.
instrumentThe rail the money came over as the operator files it (BANK_TRANSFER, CASH, WIRE, CHEQUE, …).
methodThe payment method as the provider named it, for the receipt.
providerThe provider that reported the payment. Empty for a hand-entered receipt.
received_atWhen the money moved. Omitted, it is now. It may not lie ahead of the workspace's clock (a few minutes of a provider's clock running ahead are allowed).
referenceThe provider's own reference for the event. Empty for a hand-entered receipt.
Record a payment on an invoice › Responses
OK
Refund a paid invoice
Gives money back, in full or in part. One transaction writes the credit note, moves the money over the chosen rail and records where it went. A partial refund states an amount and the reversals are derived from the atoms it covers, so the credit carries the original's rate mix and FX pins rather than a second apportionment. The answer is one InvoiceRefund whose status says what came of it: refunded (200) with the correction's fields, or approval_pending (202) when an approval checkpoint parked the refund and nothing has moved, with the parked request's fields. A gateway refund settles with the provider afterwards; GET /invoices/{id}/payments shows it. The provider refusing is 402 with code=REFUND_DECLINED. include=original, correction and replacement embed the correction's documents (sent without being asked until 2026-11-30; after that only when named).
Required scope: payment.refund (Refund payments).
path Parameters
idDocument UUID
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 refund 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.
Refund a paid invoice › Request Body
amount^-?\d+(\.\d+)?$Optional partial-refund amount in MAJOR units, in the addressed document's currency. Omit for a full refund.
currencyOptional echo-guard: must equal the document's currency when set; a different one is refused with CURRENCY_MISMATCH before any money moves.
instrumentWhere the money goes: back through the payment provider that charged it (gateway) or onto the customer's wallet in the document's currency. Omit it for the document's default rail, the default_instrument of GET /invoices/{id}/refund-rails: gateway when the provider charge can return all of the refund, otherwise wallet. That endpoint also says which of the two can take this document's refund, and how much of it.
reasonOptional classification. Omit for requested_by_customer.
reason_noteOptional free-text justification in the operator's own words. INTERNAL: shown to the approver when the invoice.refund checkpoint is on and stamped into payment-provider metadata; never shown to the customer.
Optional explicit atom reversals, as an alternative to amount. Omit both to refund the whole document.
Refund a paid invoice › Responses
OK
Which rails can take a refund of an invoice
What POST /invoices/{id}/refund would accept, rail by rail: how much the document can still give back, which of the two instruments can carry it and how much each can, and the one the money came in on. A gateway refund goes back over a succeeded provider charge and returns at most what that charge can still return, so money that came in by bank transfer, cash or the wallet is offered to the wallet only. Read by the same rule the refund applies; nothing is locked, and the refund decides again when it runs.
Required scope: invoice.read (Read invoices).
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.
Which rails can take a refund of an invoice › Responses
OK
Replay an issued invoice against its own pins
Re-assembles the document from the pins its atoms carry - product version, price, plan price, tax rule, FX snapshot - answered at the instant the document was issued, and reports the diff against what was issued. Nothing is persisted: a finalized document does not change. The answer is the DIFF and not the new figures, because returning the figures would make an issued document a function of today's catalog.
Required scope: invoice.read (Read invoices).
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.
Replay an issued invoice against its own pins › Responses
OK
Render a document to PDF on demand (live preview)
Draws the CURRENT state of a document to inline PDF bytes without persisting. Works for DRAFTS, which is what it is for. The response is NOT the legal document and carries no document hash.
Required scope: invoice.read (Read invoices).
path Parameters
idDocument UUID
query Parameters
formatOutput format (only 'pdf' is supported)
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.
Render a document to PDF on demand (live preview) › Responses
PDF file
List the SEPA pre-notifications of an invoice
The SEPA pre-notifications Kontier sent the customer for this document, newest first: the amount, the day the debit is announced for, the period, and the state of the notice's mail. A notice whose mail did not go out (delivered false, with mail_reason) announces nothing, and no debit is taken on it until a new notice is delivered.
Required scope: invoice.read (Read invoices).
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 the SEPA pre-notifications of an invoice › Responses
OK
Add tags to a invoice
Adds the given tags to the invoice and keeps the tags it already has. Returns all tags on the invoice after the change. The invoice 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 invoice › Request Body
tag_idsThe tags to add. Each must be a tag for this kind of record.
Add tags to a invoice › Responses
OK
Remove tags from a invoice
Removes the tags given in the tag_ids query parameter from the invoice 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 invoice › Responses
No Content
Reverse an invoice
Takes the whole document back by MINTING a credit note against it - the original was issued, and an issued document does not stop having existed. The answer is a Correction: it names the original, the credit note and the replacement invoice where one was produced by id, and include=original, correction and replacement embed them (sent without being asked until 2026-11-30; after that only when named). The credit is spent at once: what the original still owed is taken off it, and what the customer had already paid on it 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. Reversing twice returns the first reversal; reversing after a PARTIAL correction is refused, because part of the document has already come back and taking the full quantity again would credit it twice. It is refused with 409 (PAYMENTS_IN_FLIGHT) while a charge of the invoice is still with the payment provider, which may yet collect it.
Required scope: invoice.void (Void invoices).
path Parameters
idDocument UUID
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-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.
Reverse an invoice › Request Body
reasonWhy the document is being reversed. Persisted on the reversing document; 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.
Reverse an invoice › Responses
OK
Write off an overdue invoice
Declares an overdue document uncollectible. It reverses nothing: the supply happened, the tax was owed and the document stands. What changes is the expectation of being paid, so the balance keeps standing and the status carries the decision. Refused with 409 (PAYMENTS_IN_FLIGHT) while a charge of the invoice is still with the payment provider.
Required scope: invoice.write (Write invoices).
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.
Write off an overdue invoice › Request Body
reasonWhy the balance is not going to be collected.
Write off an overdue invoice › Responses
OK
Download XRechnung XML
Streams the EN 16931-compliant e-invoice artifact (CII XML, or the hybrid PDF/A-3 when present) for the document.
Required scope: invoice.read (Read invoices).
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 › Responses
E-invoice artifact (CII XML or hybrid PDF/A-3)