Invoice

An Invoice is a billable statement issued to a customer. It collects line items, taxes, discounts, and shipping into a single total_amount, tracks how much has been collected (amount_paid / amount_due), and exposes the actions to deliver, charge, remind, void, or render a PDF. Invoices come from two sources: created directly via createInvoice for ad-hoc billing, or generated automatically by the Subscription engine at each cycle.

Lifecycle

1. DRAFT — created and editable. Patch with updateInvoice to add items, change amounts, or move dates.
2. OPEN — finalized and ready for collection. Subscription-generated invoices skip straight to OPEN.
3. SENT / VIEWED — sendInvoice delivers the email and (optionally) attaches the PDF; last_sent_at and last_viewed_at track engagement. Emits invoice.created, invoice.finalized.
4. OVERDUE / PARTIALLY_PAID — past due_date with an outstanding balance. Dunning may take over for charge_automatically invoices. Emits invoice.payment_failed.
5. PAID — amount_due reaches zero via payInvoice or the customer's hosted payment page. Emits invoice.paid.
6. VOID / VOIDED — terminated by voidInvoice or by a dunning terminal action. Emits invoice.voided or invoice.marked_uncollectible.

Relationships

An invoice references a buyer through buyer_id (a Customer) and may be linked from a Subscription via latest_invoice_id. Each InvoiceItem may carry a price_id (linking back to a Price) and coupon_ids for line-level discounts. Successful payments produce transfers visible under the customer's order history.

Fields that matter

• status (InvoiceStatus) — DRAFT, OPEN, SENT, VIEWED, OVERDUE, PARTIALLY_PAID, PAID, UNPAID, VOID, VOIDED.
• collection_method (charge_automatically | send_invoice) — charge_automatically runs payInvoice against the customer's default instrument when the invoice opens; send_invoice waits for the customer to pay via the hosted page.
• items (InvoiceItem[]) — each line carries description, quantity, unit_price (smallest currency unit), and optionally price_id, coupon_ids, manual_tax_rate.
• due_date (ISO date) — required on create; drives OVERDUE and reminder behavior.
• is_recurring + recurrence_interval — generates child invoices on WEEKLY / BIWEEKLY / MONTHLY / QUARTERLY / YEARLY cadence; pair with recurrence_auto_send to skip the manual send step.
• amount_due / amount_paid / total_amount (number, smallest currency unit) — the running balance the dunning engine and webhooks act on.

Related

• API reference
• Guide: Send an invoice
• Guide: Configure dunning