Bills

Overview

A bill represents a single payment within a subscription. Each billing cycle, a new bill is automatically created and a payment is attempted against the customer's stored payment method. Bills provide a complete record of each payment attempt, including the amount, due date, and any associated transactions.

How bills are generated

When a subscription becomes active, the first bill is created automatically. From that point, each time a bill is successfully paid, the next bill is created for the following billing cycle. This continues until the subscription's cycle limit is reached or the subscription is cancelled.

The bill generation process follows this sequence:

Subscription is activated — the first bill is created with a status of draft.
At the bill's due date, the bill transitions to open and a payment is automatically attempted.
If the payment succeeds, the bill transitions to paid and the next bill is created.
If the payment fails, the bill transitions to past_due and will be sent to recovery or remains available for manual action.
When the cycle limit is reached, the subscription is automatically cancelled and no further bills are created.

Bill status

Each bill transitions through the following statuses:

Status	Description
`draft`	The bill has been created but payment has not yet been attempted. This is the initial status for all bills.
`open`	The bill is finalised and due to be charged (`draft`→`open` happens before the payment attempt is made).
`past_due`	A payment attempt was made and failed; the bill is `past_due` and remains available for recovery / manually paid / void. See the guide for how failed payments interact with subscription statuses for more.
`paid`	The bill has been successfully paid.
`void`	The bill has been voided and no payment will be collected. This status is irreversible.

The allowed status transitions are:

draft → open, paid, or void
open → past_due, paid or void
past_due → paid or void
paid → void
void → no further transitions

📘
Note
When a payment attempt fails, the bill transitions to past_due rather than void. This allows you to take further action, such as recovering the payment or manually marking the bill as paid or void via the API.
From past_due the bill can transition automatically to paid or void after the outcome of recovery, depending on the automatic cancellation of subscription configuration you have set.

To learn how to retrieve and update bills, see Managing Bills.