Skip to navigation
API ReferenceInvoices

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

Authentication

AuthorizationBearer

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

Path parameters

external_idstringRequired
account_idstringRequired

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

Errors

422
Unprocessable Entity Error