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:

1. Subscription is activated — the first bill is created with a status of draft.
2. At the bill's due date, a payment is automatically attempted.
3. If the payment succeeds, the bill transitions to paid and the next bill is created.
4. If the payment fails, the bill transitions to open and remains available for manual action.
5. 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:

The allowed status transitions are:

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

📘

Note

When a payment attempt fails, the bill transitions to open rather than void. This allows you to take further action, such as retrying the payment or manually marking the bill as paid or void via the API.

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