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 invoices with cursor-based pagination and the unified field.op=value filter grammar (status, customer_id, subscription_id, currency, invoice_number, created_at, updated_at, due_date, issued_at, paid_at, partially_paid).
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.
invoice_numberFilter on invoice_number (string). Operators: eq, in, contains — dot grammar, e.g. invoice_number.in=value; a bare invoice_number=value means eq. A bare comma-separated value is in-sugar: invoice_number=a,b means invoice_number.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.
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.
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 invoice_number
Case-insensitive substring match over invoice_number
statusFilter by invoice status. Filterable fields (status, customer_id, subscription_id, currency, invoice_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
Filter by invoice status. Filterable fields (status, customer_id, subscription_id, currency, invoice_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
tagFilter by tag name (repeatable, containment semantics)
Filter by tag name (repeatable, containment semantics)
countsComma-separated countable fields (status, currency) to include per-value counts for
Comma-separated countable fields (status, currency) 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 standalone draft invoice
Creates a draft invoice that is not attached to any subscription. Optional lines must be manual types. Invoice numbering is assigned at finalize. Currency falls back to the customer's preferred currency when omitted; mismatches return 409.
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 standalone draft invoice › Request Body
billing_period_endEnd of the service period the invoice covers.
billing_period_startStart of the service period the invoice covers.
buyer_referenceBuyer's routing reference (Leitweg-ID / PO number).
currencyISO 4217 currency; defaults to the customer's preferred currency when omitted.
customer_idCustomer to bill (required).
delivery_dateDate of supply (Leistungsdatum).
due_datePayment due date.
Manual line items applied inline, each validated as an AddInvoiceLineRequest.
localeRendering locale (en, de, fr, es, it, pt, nl, ja); null inherits the org default.
Arbitrary caller-supplied key/value pairs.
Create a standalone draft invoice › Responses
Created
Generate a draft invoice
Generates a draft invoice from a subscription for the given billing period.
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.
Generate a draft invoice › Request Body
billing_period_endEnd of the period to bill; defaults to the subscription's current open period when omitted.
billing_period_startStart of the period to bill; defaults to the subscription's current open period when omitted.
localeRendering locale (en, de, fr, es, it, pt, nl, ja); null inherits the org default.
subscription_idSubscription to generate an invoice for (required).
Generate a draft invoice › Responses
Created
Preview an invoice
Returns a proforma invoice preview without creating a draft. Includes all pipeline stages (product lines, add-on lines, proration, adjustments, tax).
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
billing_period_endEnd of the period to bill; defaults to the subscription's current open period when omitted.
billing_period_startStart of the period to bill; defaults to the subscription's current open period when omitted.
localeRendering locale (en, de, fr, es, it, pt, nl, ja); null inherits the org default.
subscription_idSubscription to generate an invoice for (required).
Preview an invoice › Responses
OK
Get an invoice
Retrieves a single invoice by ID, including its lines.
path Parameters
idInvoice UUID
Invoice 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 an invoice › Responses
OK
Update header fields on a draft invoice
Edits invoice-level fields (due_date, billing_period_start/end, locale, metadata) on a draft invoice. Status, currency, customer, and totals are immutable through this path.
path Parameters
idInvoice UUID
Invoice 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.
Update header fields on a draft invoice › Request Body
billing_period_endNew end of the service period; omit to leave unchanged, or send null to clear it. Must be on or after billing_period_start.
billing_period_startNew start of the service period; omit to leave unchanged, or send null to clear it.
due_dateNew payment due date; omit to leave unchanged, or send null to clear it.
localeNew rendering locale (en, de, fr, es, it, pt, nl, ja); omit to leave unchanged.
Arbitrary caller-supplied key/value pairs; replaces the existing metadata when provided.
Update header fields on a draft invoice › Responses
OK
Manually trigger a payment attempt against an invoice
Resolves the customer's payment provider, creates a fresh gateway PaymentIntent, and inserts a pending PaymentAttempt scheduled for immediate execution. Responds 202 with the attempt id and, when supported, a hosted-checkout URL.
path Parameters
idInvoice UUID
Invoice 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.
Manually trigger a payment attempt against an invoice › Responses
Accepted
List credit-note applications for an invoice
Every credit-note application that has reduced this invoice's amount_due, joined with the credit note's number / reason / status, plus a total_credited / remaining_creditable summary.
path Parameters
idInvoice UUID
Invoice 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 for an invoice › Responses
OK
Credit-note applications that have reduced this invoice's amount due.
Pagination block; this collection is returned unpaginated with a total count.
Invoice-level credit rollup so the UI can render totals without recomputing.
Finalize an invoice
Finalizes a draft invoice. May be intercepted by an approval workflow, in which case the response is 202 with the approval request instead of the invoice.
path Parameters
idInvoice UUID
Invoice 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.
Finalize an invoice › Responses
OK
Outcome-dependent: on 200 the finalized InvoiceDTO; on 202 the ApprovalRequest that intercepted finalization (poll GET /approvals/{id}).
List invoice lines
Returns the invoice's lines keyset-paginated in stable (created_at, id) order; default and maximum page size is 500. GET /invoices/{id} already embeds lines — this endpoint exists for paging through unusually large invoices.
path Parameters
idInvoice ID
Invoice ID
query Parameters
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.
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 line to a draft invoice
Adds a manual line (EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, or CREDIT) to a draft invoice. Recomputes invoice totals atomically.
path Parameters
idInvoice UUID
Invoice 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.
Add a line to a draft invoice › Request Body
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed invoice's currency. Convenience alias for unit_price when quantity is 1.
currencyOptional echo-guard: must equal the invoice's currency when set.
descriptionLine description; required unless product_id is set, in which case the product name is used.
line_typeManual line type: EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, or CREDIT; defaults to ADD_ON when omitted.
markup_percent^-?\d+(\.\d+)?$Optional markup applied on top of a product-resolved price, as a percentage (0-1000); ignored when product_id is not set.
Arbitrary caller-supplied key/value pairs.
period_endOptional end of the service period this line covers; must be on or after period_start.
period_startOptional start of the service period this line covers.
product_idOptional catalog product; when set, the service resolves the active price and description and unit_price may be omitted.
quantity^-?\d+(\.\d+)?$Billed quantity; defaults to 1 when omitted. Must be positive.
tax_category_codeEN16931 VAT category (S/Z/E/AE/K/G/O); when set, overrides tax resolution for this line.
tax_exemption_reasonBT-120 exemption reason text; required when tax_category_code is a non-standard (Z/E/AE/K/G/O) category.
tax_rate^-?\d+(\.\d+)?$Optional tax rate override for this line, as a fraction between 0 and 1 (0.19 = 19%).
unit_price^-?\d+(\.\d+)?$MAJOR units, in the addressed invoice's currency.
Add a line to a draft invoice › Responses
Created
Delete a line from a draft invoice
Removes a line from a draft invoice and recomputes totals atomically.
path Parameters
idInvoice UUID
Invoice UUID
lineIdLine UUID
Line 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.
Delete a line from a draft invoice › Responses
No Content
Update a line on a draft invoice
Edits one or more fields on a single line. Only legal while the invoice is in draft. Subtotal and tax_amount are recomputed automatically.
path Parameters
idInvoice UUID
Invoice UUID
lineIdLine UUID
Line 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.
Update a line on a draft invoice › Request Body
currencyOptional echo-guard: must equal the invoice's currency when set.
descriptionNew line description; omit to leave unchanged, must be non-empty when provided.
Arbitrary caller-supplied key/value pairs; replaces the existing metadata when provided.
period_endNew end of the service period this line covers; omit to leave unchanged. Must be on or after period_start.
period_startNew start of the service period this line covers; omit to leave unchanged.
quantity^-?\d+(\.\d+)?$New billed quantity; omit to leave unchanged. Must be positive.
tax_rate^-?\d+(\.\d+)?$New tax rate as a fraction between 0 and 1 (0.19 = 19%); omit to leave unchanged.
unit_price^-?\d+(\.\d+)?$MAJOR units, in the addressed invoice's currency.
Update a line on a draft invoice › Responses
OK
List payments recorded against an invoice
The invoice's full payment timeline - v2 gateway payments (any lifecycle state) merged with operator-recorded manual payments, newest first.
path Parameters
idInvoice UUID
Invoice 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 invoice PDF. Within the post-finalize grace window a missing artifact responds 409 with Retry-After while the document worker renders it.
path Parameters
idInvoice UUID
Invoice 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 manual payment on an invoice
Records a source-classified manual payment against a finalized or overdue invoice. The body requires amount AND source; reference, note, received_at are optional.
path Parameters
idInvoice UUID
Invoice 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 a manual payment on an invoice › Request Body
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed invoice's currency.
currencyOptional echo-guard: must equal the invoice's currency when set.
notereceived_atreferencesourceRecord a manual payment on an invoice › Responses
OK
Refund a paid invoice
Initiates a refund (full or partial) against a paid invoice. Generates a credit note and, when applicable, instructs the payment gateway to release funds. Responds 202 when the gateway confirms asynchronously.
path Parameters
idInvoice UUID
Invoice UUID
Headers
Idempotency-KeyIdempotency key threaded into the refund as its dedup token
Idempotency 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 invoice's currency. Omit for a full refund of amount_paid.
currencyOptional echo-guard: must equal the invoice's currency when set.
reasonOptional refund classification: duplicate, fraudulent, requested_by_customer, service_issue, or other. Empty defaults to requested_by_customer.
Refund a paid invoice › Responses
OK
Outcome-dependent: on 200 the VoidInvoiceResponseDTO (voided invoice + credit note); on 202 the RefundInvoiceResponse with status=refund_pending while the gateway refund settles (observe completion via GET /invoices/{id}/payments).
Regenerate (preview) an invoice using pinned price snapshots
Re-runs the invoice pipeline against the original invoice's price_version pins, returning a proforma + diff vs the original. Nothing is persisted. Read-only sibling of POST /invoices/preview.
path Parameters
idInvoice UUID
Invoice 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.
Regenerate (preview) an invoice using pinned price snapshots › Responses
OK
Render an invoice to PDF on demand (live preview)
Renders the CURRENT persisted state of an invoice to inline PDF bytes on the fly, without persisting. Works for DRAFT invoices too; the response is NOT the legal document and carries no document hash.
path Parameters
idInvoice UUID
Invoice UUID
query Parameters
formatOutput format (only 'pdf' is supported)
Output 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 an invoice to PDF on demand (live preview) › Responses
PDF file
Void an invoice
Voids a finalized invoice and creates a corresponding credit note.
path Parameters
idInvoice UUID
Invoice 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 an invoice › Responses
OK
Download XRechnung XML
Streams the EN 16931-compliant e-invoice artifact (CII XML, or hybrid PDF/A-3 when present) for the invoice.
path Parameters
idInvoice UUID
Invoice 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)