Finalize Invoice
Finalize an invoice (transition from DRAFT to OPEN).
Triggers PDF generation after finalization. Validates domain invariants post-finalization.
Requirements:
- Invoice must be in DRAFT state
- Invoice must have at least one line item (unless setup mode)
Returns:
- The finalized invoice with OPEN status
409 invoice_busy (retryable: true): another operation held the invoice, so
nothing was changed. Retry. If you send an Idempotency-Key, send a new one: the
key stores this 409 too.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Headers
Response
Custom field values. Only included when expand=custom_fields is specified.
Free-text note attached to this invoice, from the notes side-table. Merchant-private — unlike description, it never appears on the invoice PDF or any customer-facing surface.
Why an invoice exists. Re-exported from invoices_schemas for
backwards compatibility — new code should import it from here.
Lives in this dependency-free module, rather than in invoices_schemas,
because the payments side needs it too: payment_intents snapshots the
producing invoice’s reason (see PaymentIntentEntity.invoice_billing_reason)
and importing invoices_schemas from intents_model would drag half of
billing into the payments import graph. Same reasoning that moved the
PaymentIntent enums into intents_enums.
False when the checkout session that created this invoice opted out of the customer’s credit balance (no credit applied; a debt is still settled).
The processor route pinned to this invoice at create (processor_route_id on POST /invoices), or null when none is. While the account’s routing engine is on and the route is active, the invoice’s card charges go through it, ahead of the subscription’s pinned route, routing rules and the account default. A collection that would charge none of its cards through it routes as if the invoice had no route.