Skip to navigation

Finalize Invoice

View as Markdown

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

external_idstringRequired
account_idstringRequired

Headers

Idempotency-Keystring or nullOptional>=8 characters
A unique key for this request. A retry with the same key returns the first response instead of running again, for 24 hours. Keys are per caller.

Response

Successful Response
idstring
customer_idstring
statusenum
currencyenum
ISO 4217 currency codes.
subtotal_amount_atominteger or null
tax_amount_atominteger or null
total_amount_atominteger or null
due_amount_atominteger or null
paid_amount_atominteger or null
remaining_amount_atominteger or null
issued_atdatetime
due_datedatetime or null
descriptionstring or null
metadatamap from strings to any or null
created_atdatetime
updated_atdatetime
applied_balance_amount_atominteger or nullOptional
total_discount_amount_atominteger or nullOptional
period_startdatetime or nullOptional
period_enddatetime or nullOptional
collection_methodenumOptional
Allowed values:
custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

notestring or nullOptional

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.

itemslist of objectsOptional
invoice_numberinteger or nullOptional
billing_reasonenum or nullOptional

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.

subscription_idstring or nullOptional
payment_method_idstring or nullOptional
invoice_pdf_urlstring or nullOptional
receipt_pdf_urlstring or nullOptional
hosted_invoice_urlstring or nullOptional
apply_customer_balancebooleanOptionalDefaults to true

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).

processor_route_idstring or nullOptional

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.

Errors

422
Unprocessable Entity Error