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).
query Parameters
limitPage size
cursorPagination cursor
statusFilter by invoice status (sugar for status.eq=...; supports status.in=a,b)
customer_idFilter by customer UUID (supports customer_id.in=...)
List invoices › Responses
Paginated list wrapped in data envelope
amount_dueamount_paidbilling_period_endbilling_period_startbuyer_referenceLeitweg-ID / PO number
created_atcurrencycustomer_idcustomer_profile_at_issueCustomerProfileAtIssue pins the buyer's CustomerType profile (BUSINESS / CONSUMER / UNKNOWN) at finalize time. Regenerate uses this snapshot (NOT live customer.CustomerType) so a later profile flip cannot retroactively re-classify a closed invoice's supply type or reverse-charge gating. Audit-layer addition for ADR-0004 Decision 4 (billing-audit workstream 11).
Nil for legacy invoices written before migration 007.
deleted_atdelivery_dateLeistungsdatum (§14 Abs. 4 Nr. 6)
due_dateidinvoice_numberinvoice_typeINVOICE, CREDIT_NOTE, CORRECTIVE
issue_exchange_rate_idissued_atlast_dunning_step_atlast_dunning_step_indexlocaleorganization_idpaid_atperiod_start_exchange_rate_idplan_idPlanID / PlanVersion stamp the plan-version snapshot pinned at finalize. Regenerate uses these (NOT live sub.PlanID/PlanVersion) to reproduce historical invoices byte-for-byte, satisfying ADR-0004 rule 4: "plan-version snapshot is immutable post-publish."
Sourced from the active subscription_plan_version_history row at the invoice's billing_period_start (or first segment's start - see pipeline_finalize.stampPlanSnapshot for the chosen anchor).
Nil for plan-less subscriptions (item-only billing).
plan_versionstatussubscription_idsubtotalsupplier_tax_numberDenormalized for rendering
supplier_vat_idDenormalized for rendering
supply_typeDOMESTIC, INTRA_EU_B2B, etc.
tax_category_codeEN 16931 BT-151
tax_exemption_reason"Reverse Charge §13b UStG" etc.
tax_point_dateSteuerentstehung
tax_totaltotalupdated_atCreate a standalone draft invoice
Creates a draft invoice that is not attached to any subscription (subscription_id is null). Optional lines must be manual types (EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, CREDIT, or default ADD_ON). Invoice numbering is assigned at finalize, sharing the same sequence as subscription-generated invoices. Currency falls back to the customer's preferred currency when omitted; mismatches return 409.
Create a standalone draft invoice › Request Body
billing_period_endbilling_period_startbuyer_referencecurrencycustomer_iddelivery_datedue_datelocaleCreate a standalone draft invoice › Responses
Newly created draft invoice
billing_period_endbilling_period_startbuyer_referencecreated_atcurrencycustomer_iddeleted_atdelivery_datedue_dateidinvoice_numberinvoice_typeissued_atlast_dunning_step_atlast_dunning_step_indexlocaleorganization_idpaid_atstatussubscription_idsupplier_tax_numbersupplier_vat_idsupply_typetax_category_codetax_exemption_reasontax_point_dateupdated_atGenerate a draft invoice
Generates a draft invoice from a subscription for the given billing period
Generate a draft invoice › Request Body
billing_period_endbilling_period_startlocalesubscription_idGenerate a draft invoice › Responses
Wrapped in data envelope
amount_dueamount_paidbilling_period_endbilling_period_startbuyer_referenceLeitweg-ID / PO number
created_atcurrencycustomer_idcustomer_profile_at_issueCustomerProfileAtIssue pins the buyer's CustomerType profile (BUSINESS / CONSUMER / UNKNOWN) at finalize time. Regenerate uses this snapshot (NOT live customer.CustomerType) so a later profile flip cannot retroactively re-classify a closed invoice's supply type or reverse-charge gating. Audit-layer addition for ADR-0004 Decision 4 (billing-audit workstream 11).
Nil for legacy invoices written before migration 007.
deleted_atdelivery_dateLeistungsdatum (§14 Abs. 4 Nr. 6)
due_dateidinvoice_numberinvoice_typeINVOICE, CREDIT_NOTE, CORRECTIVE
issue_exchange_rate_idissued_atlast_dunning_step_atlast_dunning_step_indexlocaleorganization_idpaid_atperiod_start_exchange_rate_idplan_idPlanID / PlanVersion stamp the plan-version snapshot pinned at finalize. Regenerate uses these (NOT live sub.PlanID/PlanVersion) to reproduce historical invoices byte-for-byte, satisfying ADR-0004 rule 4: "plan-version snapshot is immutable post-publish."
Sourced from the active subscription_plan_version_history row at the invoice's billing_period_start (or first segment's start - see pipeline_finalize.stampPlanSnapshot for the chosen anchor).
Nil for plan-less subscriptions (item-only billing).
plan_versionstatussubscription_idsubtotalsupplier_tax_numberDenormalized for rendering
supplier_vat_idDenormalized for rendering
supply_typeDOMESTIC, INTRA_EU_B2B, etc.
tax_category_codeEN 16931 BT-151
tax_exemption_reason"Reverse Charge §13b UStG" etc.
tax_point_dateSteuerentstehung
tax_totaltotalupdated_atPreview an invoice
Returns a proforma invoice preview without creating a draft. Includes all pipeline stages (product lines, add-on lines, proration, adjustments, tax).
Preview an invoice › Request Body
billing_period_endbilling_period_startlocalesubscription_idPreview an invoice › Responses
Wrapped in data envelope
amount_dueamount_paidbilling_period_endbilling_period_startbuyer_referenceLeitweg-ID / PO number
created_atcurrencycustomer_idcustomer_profile_at_issueCustomerProfileAtIssue pins the buyer's CustomerType profile (BUSINESS / CONSUMER / UNKNOWN) at finalize time. Regenerate uses this snapshot (NOT live customer.CustomerType) so a later profile flip cannot retroactively re-classify a closed invoice's supply type or reverse-charge gating. Audit-layer addition for ADR-0004 Decision 4 (billing-audit workstream 11).
Nil for legacy invoices written before migration 007.
deleted_atdelivery_dateLeistungsdatum (§14 Abs. 4 Nr. 6)
due_dateidinvoice_numberinvoice_typeINVOICE, CREDIT_NOTE, CORRECTIVE
issue_exchange_rate_idissued_atlast_dunning_step_atlast_dunning_step_indexlocaleorganization_idpaid_atperiod_start_exchange_rate_idplan_idPlanID / PlanVersion stamp the plan-version snapshot pinned at finalize. Regenerate uses these (NOT live sub.PlanID/PlanVersion) to reproduce historical invoices byte-for-byte, satisfying ADR-0004 rule 4: "plan-version snapshot is immutable post-publish."
Sourced from the active subscription_plan_version_history row at the invoice's billing_period_start (or first segment's start - see pipeline_finalize.stampPlanSnapshot for the chosen anchor).
Nil for plan-less subscriptions (item-only billing).
plan_versionstatussubscription_idsubtotalsupplier_tax_numberDenormalized for rendering
supplier_vat_idDenormalized for rendering
supply_typeDOMESTIC, INTRA_EU_B2B, etc.
tax_category_codeEN 16931 BT-151
tax_exemption_reason"Reverse Charge §13b UStG" etc.
tax_point_dateSteuerentstehung
tax_totaltotalupdated_atGet an invoice
Retrieves a single invoice by ID, including its lines
path Parameters
idInvoice UUID
Get an invoice › Responses
Wrapped in data envelope
amount_dueamount_paidbilling_period_endbilling_period_startbuyer_referenceLeitweg-ID / PO number
created_atcurrencycustomer_idcustomer_profile_at_issueCustomerProfileAtIssue pins the buyer's CustomerType profile (BUSINESS / CONSUMER / UNKNOWN) at finalize time. Regenerate uses this snapshot (NOT live customer.CustomerType) so a later profile flip cannot retroactively re-classify a closed invoice's supply type or reverse-charge gating. Audit-layer addition for ADR-0004 Decision 4 (billing-audit workstream 11).
Nil for legacy invoices written before migration 007.
deleted_atdelivery_dateLeistungsdatum (§14 Abs. 4 Nr. 6)
due_dateidinvoice_numberinvoice_typeINVOICE, CREDIT_NOTE, CORRECTIVE
issue_exchange_rate_idissued_atlast_dunning_step_atlast_dunning_step_indexlocaleorganization_idpaid_atperiod_start_exchange_rate_idplan_idPlanID / PlanVersion stamp the plan-version snapshot pinned at finalize. Regenerate uses these (NOT live sub.PlanID/PlanVersion) to reproduce historical invoices byte-for-byte, satisfying ADR-0004 rule 4: "plan-version snapshot is immutable post-publish."
Sourced from the active subscription_plan_version_history row at the invoice's billing_period_start (or first segment's start - see pipeline_finalize.stampPlanSnapshot for the chosen anchor).
Nil for plan-less subscriptions (item-only billing).
plan_versionstatussubscription_idsubtotalsupplier_tax_numberDenormalized for rendering
supplier_vat_idDenormalized for rendering
supply_typeDOMESTIC, INTRA_EU_B2B, etc.
tax_category_codeEN 16931 BT-151
tax_exemption_reason"Reverse Charge §13b UStG" etc.
tax_point_dateSteuerentstehung
tax_totaltotalupdated_atUpdate 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
Update header fields on a draft invoice › Request Body
billing_period_endbilling_period_startdue_datelocaleUpdate header fields on a draft invoice › Responses
Updated invoice
billing_period_endbilling_period_startbuyer_referencecreated_atcurrencycustomer_iddeleted_atdelivery_datedue_dateidinvoice_numberinvoice_typeissued_atlast_dunning_step_atlast_dunning_step_indexlocaleorganization_idpaid_atstatussubscription_idsupplier_tax_numbersupplier_vat_idsupply_typetax_category_codetax_exemption_reasontax_point_dateupdated_atManually 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. The retry worker picks up the row on its next poll. Returns 202 with the attempt id.
path Parameters
idInvoice UUID
Manually trigger a payment attempt against an invoice › Responses
Wrapped in data envelope
attempt_idattempt_numbercheckout_urlCheckoutURL is the provider's hosted-checkout URL the frontend must redirect the customer to in order to complete the payment. Empty for providers that don't support a hosted flow (callers should branch on this and surface a different "add payment method first" UX instead).
invoice_idproviderscheduled_forList credit-note applications for an invoice
Returns every credit-note application that has reduced this invoice's amount_due, joined with the credit note's number / reason / status. Used by the invoice detail page's "credits applied" timeline. Includes a summary of total_credited and remaining_creditable so the UI can render "€450 of €1,200 credited across 2 notes" without recomputing client-side.
path Parameters
idInvoice UUID
List credit-note applications for an invoice › Responses
Per-invoice credit timeline + summary
Finalize an invoice
Finalizes a draft invoice, transitioning it to finalized status. May be intercepted by an approval workflow.
path Parameters
idInvoice UUID
Finalize an invoice › Responses
Wrapped in data envelope
amount_dueamount_paidbilling_period_endbilling_period_startbuyer_referenceLeitweg-ID / PO number
created_atcurrencycustomer_idcustomer_profile_at_issueCustomerProfileAtIssue pins the buyer's CustomerType profile (BUSINESS / CONSUMER / UNKNOWN) at finalize time. Regenerate uses this snapshot (NOT live customer.CustomerType) so a later profile flip cannot retroactively re-classify a closed invoice's supply type or reverse-charge gating. Audit-layer addition for ADR-0004 Decision 4 (billing-audit workstream 11).
Nil for legacy invoices written before migration 007.
deleted_atdelivery_dateLeistungsdatum (§14 Abs. 4 Nr. 6)
due_dateidinvoice_numberinvoice_typeINVOICE, CREDIT_NOTE, CORRECTIVE
issue_exchange_rate_idissued_atlast_dunning_step_atlast_dunning_step_indexlocaleorganization_idpaid_atperiod_start_exchange_rate_idplan_idPlanID / PlanVersion stamp the plan-version snapshot pinned at finalize. Regenerate uses these (NOT live sub.PlanID/PlanVersion) to reproduce historical invoices byte-for-byte, satisfying ADR-0004 rule 4: "plan-version snapshot is immutable post-publish."
Sourced from the active subscription_plan_version_history row at the invoice's billing_period_start (or first segment's start - see pipeline_finalize.stampPlanSnapshot for the chosen anchor).
Nil for plan-less subscriptions (item-only billing).
plan_versionstatussubscription_idsubtotalsupplier_tax_numberDenormalized for rendering
supplier_vat_idDenormalized for rendering
supply_typeDOMESTIC, INTRA_EU_B2B, etc.
tax_category_codeEN 16931 BT-151
tax_exemption_reason"Reverse Charge §13b UStG" etc.
tax_point_dateSteuerentstehung
tax_totaltotalupdated_atList invoice lines
Lists all lines for a given invoice
path Parameters
idInvoice UUID
List invoice lines › Responses
Paginated list wrapped in data envelope
AppliedPromotions holds the audit-layer snapshot of every promotion that touched this line's subtotal at finalize. Regenerate reads these (NOT the live promotion catalog) and replays the cents verbatim. Per ADR-0004 Decision 4 and billing-audit workstream 10: voiding or editing a promotion does not change historical totals.
charge_ledger_idChargeLedgerID back-references the single charge_ledger row that produced this line when no collapse happened. Nil for lines built by the resolver-at-invoice-time path (still the default for SEAT / USAGE / ADD_ON / proration as of PR 2), for lines that merged multiple ledger rows, or for manually edited lines. Persisted in invoice_lines.charge_ledger_id; the authoritative reverse mapping is charge_ledger.invoice_line_id (set inside the same tx as the invoice insert).
created_atdescriptionfx_policy_appliedidinvoice_idline_typeorganization_idperiod_endperiod_startprice_keyprice_key_display_nameprice_version_idproduct_idquantitysegment_exchange_rate_idsubtotaltax_amounttax_category_codeEN 16931 BT-151: S, Z, E, AE, K, G, O
tax_exemption_reasonBT-120: per-line reason text
tax_ratetax_rule_idtax_typeunit_priceAdd a line to a draft invoice
Adds a manual line (EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, or CREDIT) to a draft invoice. Defaults to EXPENSE_PASSTHROUGH for backwards compatibility with the legacy expense-only endpoint. Markup percent only applies to expense pass-through lines; ignored otherwise. Recomputes invoice totals atomically.
path Parameters
idInvoice UUID
Add a line to a draft invoice › Request Body
amountdescriptionline_typemarkup_percentperiod_endperiod_startproduct_idquantitytax_rateunit_priceAdd a line to a draft invoice › Responses
Newly created line
created_atcurrencydescriptionidinvoice_idline_typeorganization_idperiod_endperiod_startprice_keyprice_key_display_nameproduct_idquantitytax_category_codetax_exemption_reasontax_ratetax_typeDelete a line from a draft invoice
Removes a line from a draft invoice and recomputes totals atomically. Only legal while the invoice is in draft. Audit event invoice.line_deleted carries the deleted line's snapshot.
path Parameters
idInvoice UUID
line_idLine UUID
Delete a line from a draft invoice › Responses
Line deleted
Update a line on a draft invoice
Edits one or more fields (description, quantity, unit_price, tax_rate, period dates, metadata) on a single line. Only legal while the invoice is in draft. Subtotal and tax_amount are recomputed automatically. Audit event invoice.line_updated carries the before/after diff.
path Parameters
idInvoice UUID
line_idLine UUID
Update a line on a draft invoice › Request Body
descriptionperiod_endperiod_startquantitytax_rateunit_priceUpdate a line on a draft invoice › Responses
Updated line
created_atcurrencydescriptionidinvoice_idline_typeorganization_idperiod_endperiod_startprice_keyprice_key_display_nameproduct_idquantitytax_category_codetax_exemption_reasontax_ratetax_typeList payments recorded against an invoice
Returns the invoice's full payment timeline - v2 gateway payments (Stripe / GoCardless, in any lifecycle state) merged with operator-recorded manual payments, newest first. Powers the invoice detail "Payments" tab so operators can see which payments were made / attempted and how.
path Parameters
idInvoice UUID
List payments recorded against an invoice › Responses
Invoice payment timeline
Record a manual payment on an invoice
Records a source-classified manual payment against a finalized or overdue invoice. The body now requires amount AND source; reference, note, received_at are optional. The legacy "amount-only" body shape is no longer accepted (pre-prod migration; see M200).
path Parameters
idInvoice UUID
Record a manual payment on an invoice › Request Body
amountnotereceived_atreferencesourceRecord a manual payment on an invoice › Responses
Wrapped in data envelope
amount_dueamount_paidbilling_period_endbilling_period_startbuyer_referenceLeitweg-ID / PO number
created_atcurrencycustomer_idcustomer_profile_at_issueCustomerProfileAtIssue pins the buyer's CustomerType profile (BUSINESS / CONSUMER / UNKNOWN) at finalize time. Regenerate uses this snapshot (NOT live customer.CustomerType) so a later profile flip cannot retroactively re-classify a closed invoice's supply type or reverse-charge gating. Audit-layer addition for ADR-0004 Decision 4 (billing-audit workstream 11).
Nil for legacy invoices written before migration 007.
deleted_atdelivery_dateLeistungsdatum (§14 Abs. 4 Nr. 6)
due_dateidinvoice_numberinvoice_typeINVOICE, CREDIT_NOTE, CORRECTIVE
issue_exchange_rate_idissued_atlast_dunning_step_atlast_dunning_step_indexlocaleorganization_idpaid_atperiod_start_exchange_rate_idplan_idPlanID / PlanVersion stamp the plan-version snapshot pinned at finalize. Regenerate uses these (NOT live sub.PlanID/PlanVersion) to reproduce historical invoices byte-for-byte, satisfying ADR-0004 rule 4: "plan-version snapshot is immutable post-publish."
Sourced from the active subscription_plan_version_history row at the invoice's billing_period_start (or first segment's start - see pipeline_finalize.stampPlanSnapshot for the chosen anchor).
Nil for plan-less subscriptions (item-only billing).
plan_versionstatussubscription_idsubtotalsupplier_tax_numberDenormalized for rendering
supplier_vat_idDenormalized for rendering
supply_typeDOMESTIC, INTRA_EU_B2B, etc.
tax_category_codeEN 16931 BT-151
tax_exemption_reason"Reverse Charge §13b UStG" etc.
tax_point_dateSteuerentstehung
tax_totaltotalupdated_atRefund 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.
path Parameters
idInvoice UUID
Refund a paid invoice › Responses
Generated credit note
created_atcredit_note_numbercurrencycustomer_iddeleted_atidinvoice_idissued_atorganization_idreasonreason_codestatusupdated_atvoided_atRegenerate (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. Lines whose original had no version pin fall through to live resolution.
path Parameters
idInvoice UUID
Regenerate (preview) an invoice using pinned price snapshots › Responses
Wrapped in data envelope
missing_product_idsnew_product_idsoriginal_invoice_idsubtotal_deltatax_deltatotal_delta