Skip to main content
Every subscription cycle produces an invoice (inv_). It carries the amount requested from the customer, the payment attempt history, and the payment link sent by email.

​
The invoice object

The fields that matter for a subscription (camelCase):
​
string
Identifier, prefixed inv_.
​
string | null
Sequential number, set at finalization. null on a proration invoice.
​
string
draft, open, paid, void, uncollectible. See below.
​
string
Why the invoice exists: subscription_create (first period, API creation without a trial — and first paid period after a trial), subscription_cycle (renewal), proration (mid-period quantity increase), subscription_update, manual (outside a subscription).
​
string | null
The subscription, sub_….
​
string | null
The customer, cus_….
​
string
Currency, lowercase.
​
number
The line totals.
​
number
Customer credit applied to this invoice.
​
number
total − appliedBalance: what is actually requested from the customer.
​
number
Collected and remaining.
​
string | null
The period covered.
​
…
Payment attempt history and the reason for the last failure.
​
string | null
The date of each step.
​
string | null
The payment link sent to the customer (hosted page).
​
string | null
The PDF, once generated.
​
array
The lines: description, quantity, unitAmount, amount, taxAmount, priceId, periodStart, periodEnd.

​
The statuses

​
Listing a subscription’s invoices

All invoices, newest first, without pagination, each with its order and lines. Proration invoices are included.
The general list, paginated, filterable by status, customer_id, subscription_id, from, to.

​
Read, download, close

Voiding a cycle’s invoice does not stop already-scheduled retries, and does not change the subscription’s past_due status: they are two objects. To stop billing, act on the subscription (cancel or pause).

​
Previewing the next invoice

Returns what the next cycle will bill, computed by the same calculator as the real invoice, without writing anything.
200
With ?subscription_item_id=si_...&quantity=5, the preview simulates a quantity change: billingReason becomes proration, a proration line for the rest of the current period is added, and the discount is not spread (discountTotal: 0). The real amount is computed at the time of the change — see Change the quantity.

​
Customer balance

A credit granted to the customer (POST /v1/customers/{id}/balance/credit) is applied automatically to the next cycle invoice: appliedBalance goes up, amountDue goes down, and if the credit covers everything, no payment request goes out. See Customers.