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, the bill transitions to open and 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 past_due and will be sent to recovery or remains available for manual action.
5. When the cycle limit is reached, the subscription is automatically cancelled and no further bills are created.

---

Payment webhook notifications

Each time a payment is attempted against a bill, a status_update webhook is sent to the subscription's webhook_url. The webhook body includes the subscription_id and bill_id, so you can tie the payment outcome back to the exact bill. For the payload, field details, and an example, see Bill Payment Webhooks.

---

Bill status

Each bill transitions through the following statuses:

The allowed status transitions are:

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

---

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

---

Bill payment timing

The default behaviour for setting payment times of all Bills is to take the same time as the subscription was activated. E.g.: activation occurred at 11:23am on Jan 1st, all future Bill payments taken at 11:23am on the 1st of Feb, Mar, etc.

If the subscription has a trial, the trial end date takes over as the anchor instead. The first paid Bill is taken at the trial end, and all future Bills work off that.

When you activate a subscription with an external transaction_id the clock starts from when you activate, not from when that external transaction actually happened.

Key takeaways:

• The anchor for Bill payment timing is picked in this order: trial end → activation time. If a trial is set, its end date wins; otherwise the schedule anchors to when the subscription was activated.
• Prepaid caveat: if the external payment happened days before you activate, the schedule drifts to activation + cycle, not real-payment + cycle. To bill on the original date, activate as close as possible to when the external payment was taken.