The invoice object

{
  "id": "inv_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "invoice",
  "number": null,
  "customer": "cus_01JEXAMPLE2K8V4N9C6M1Q7R",
  "subscription": null,
  "status": "draft",
  "collection_method": "charge_automatically",
  "currency": "usd",
  "total": 2500,
  "amount_paid": 2500,
  "amount_remaining": 0,
  "hosted_invoice_url": null,
  "livemode": false
}

An Invoice (inv_…) bills a customer. Your server creates one-off invoices, and a subscription generates one at each period boundary. An invoice item (ii_…) is a pending charge recorded against a customer. When you create an invoice for that customer, every pending item in the invoice currency is drained onto the new draft as a line (il_…). See Invoices for the full flow. A draft can be edited freely. Finalizing it assigns a gapless, sequential number per merchant and mode (for example INV-000001), applies tax, freezes the lines, and opens the invoice. Drafts carry no number, so an abandoned draft never consumes one. A paid invoice can be offset with a credit note. Platforms can create and manage billing for connected accounts: see Billing for connected accounts.

Attributes

string

The invoice id (inv_…).

string | null

The gapless per-merchant number, assigned at finalize. Null while draft.

string

The billed customer (cus_…), set at creation and immutable.

string | null

The subscription that generated this invoice (sub_…). Absent for one-off invoices created directly against a customer.

string

One of draft (being built, lines mutable, never customer-visible), open (finalized, lines frozen, awaiting payment), paid (terminal; reachable from open, from uncollectible via a late payment, or directly at finalize when the total is zero), void (terminal; requires amount_paid of zero), or uncollectible (written off; not terminal, since a late payment can still move it to paid).

string

One of charge_automatically (charged automatically against the pinned payment method) or send_invoice (the buyer pays through the hosted invoice page, with an optional due_date).

string

Three-letter ISO currency code. USD, EUR, and GBP are supported; all use 2-decimal minor units.

integer

subtotal plus tax minus discounts, in minor units. Discounts can reduce this to zero but never below it.

integer

The cumulative amount paid so far, in minor units.

integer

total minus amount_paid, in minor units.

string | null

The buyer-facing hosted invoice page URL. Present once the invoice has been finalized and hosted invoicing is enabled for the deployment; null on drafts or when hosted invoicing is not configured.

See every field in the response of Retrieve an invoice.

Endpoints

Endpoint	Use it for
Create an invoice item	Record a pending charge against a customer.
Retrieve an invoice item	Fetch one invoice item.
Update an invoice item	Change a pending invoice item.
Delete an invoice item	Remove a pending invoice item.
Create an invoice	Create a draft for a customer.
List invoices	Review invoices, optionally filtered by status.
Retrieve an invoice	Check the current status and amounts.
Download an invoice PDF	Render the invoice and its recorded payments as a PDF.
Update an invoice’s payment method	Set or replace the payment method pinned for collection on an open invoice.
Add a line to a draft invoice	Add a line while the invoice is a draft.
Remove a line from a draft invoice	Remove a line while the invoice is a draft.
Finalize an invoice	Move a draft to open, or to paid when the total is zero.
Collect payment on an invoice	Charge an open `charge_automatically` invoice against the customer’s saved card.
Void an invoice	Void an open invoice that has taken no payment.
Mark an invoice uncollectible	Write off an open invoice and keep the balance for reporting.
List an invoice’s payment attempts	See the collection attempts recorded for an invoice, newest first.

Statuses

Status	Meaning
`draft`	Being built. Lines are mutable and the invoice is never customer-visible.
`open`	Finalized, lines frozen, awaiting payment.
`paid`	Terminal. Reachable from `open`, from `uncollectible` through a late payment, or directly at finalize when the total is zero.
`void`	Terminal. Requires `amount_paid` of zero.
`uncollectible`	Written off. Not terminal, because a late payment can still move it to `paid`.

Collection methods

Method	Behavior
`charge_automatically`	Charged automatically against the pinned payment method.
`send_invoice`	The buyer pays through the hosted invoice page, with an optional `due_date`.

Payment attempts

Each automatic collection attempt is recorded as an invoice_payment_attempt with a status of pending, succeeded, failed, or blocked. pending means the final outcome is not known yet. Retrieve the attempts again before retrying.

Notes

Live invoice numbers use INV-000001 style labels. Test invoice numbers use TEST-INV-000001.
An authorized platform can call every invoice and invoice item endpoint for a connected account by sending Ionic-Account. See Bill a connected account.
Mutating endpoints accept an optional Idempotency-Key header. See Idempotency.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

Attributes

Endpoints

Statuses

Collection methods

Payment attempts

Notes

​Attributes

​Endpoints

​Statuses

​Collection methods

​Payment attempts

​Notes

Attributes

Endpoints

Statuses

Collection methods

Payment attempts

Notes