Subscriptions & dunning
Recurring plans collected each period by emailed invoice, saved card or direct-debit mandate, with courtesy reminders and zero late-payment penalties.
How a subscription is billed
Start a subscription from a flat or per-seat plan with POST /v1/billing/subscriptions. The first invoice is made at once, or when the free trial ends, and a new one is made at the start of every period.
Tiered and usage plans are not billed automatically yet.
Webhooks: subscription.created, subscription.renewed (each period after the first is billed), subscription.past_due, subscription.paused, subscription.resumed and subscription.canceled.
How each invoice is collected
Set collectionMethod when you create the subscription. Each period the invoice is made first, then collected. If the charge fails, or there is nothing to charge yet, the invoice is emailed to the customer with its pay link, so they can always pay.
The card or mandate must belong to the same customer (the same email) and be in the same mode as the subscription.
When the card or mandate goes away
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| send_invoice | collectionMethod | Optional | The default. Each invoice is emailed to the customer with its pay link. |
| card | collectionMethod | Optional | Each invoice is charged to a saved card. Pass paymentMethodId (pm_...). You may leave it out: the first invoice is then emailed, its checkout offers to save the card, and the card saved there is used from then on. |
| mandate | collectionMethod | Optional | Each invoice is debited from a direct-debit mandate. mandateId (mnd_...) is required, and the mandate must be active. |
Dunning schedule
An invoice not paid by its due date is overdue. The customer gets a courtesy email on days 1, 3, 7 and 14 overdue, the subscription becomes past_due (subscription.past_due), and a month after the due date it is cancelled (subscription.canceled). Paying the invoice at any point brings the subscription back to active. The customer owes only the fixed subscription price — never a penalty or compounding charge.