Subscriptions
A subscription represents an ongoing billing relationship between you and a customer.
When should I read this?
Read this if you need to understand how subscriptions are created, how they progress through their lifecycle, or how billing works.
What is a subscription?
A subscription connects:
- Customer — who is being billed
- Product/Price — what they're paying for
- Billing schedule — when invoices are generated
- Status — current state of the subscription
Subscription lifecycle
Created → Active → (Canceled/Expired)
| Status | Description |
|---|---|
pending |
Created but not yet active |
active |
Currently billing |
paused |
Temporarily stopped, can resume |
canceled |
Ended by request, may continue until period end |
expired |
Reached end of term |
Key dates
- Start date — when billing begins
- Current period start/end — the active billing window
- Cancel at period end — if true, subscription ends when current period expires
Billing behavior
Subscriptions generate invoices automatically:
- At subscription start
- At each renewal (monthly, yearly, etc.)
- When usage is finalized (for usage-based pricing)
Common operations
- Create — start a new subscription
- Update — change quantity, add items
- Pause — temporarily stop billing
- Cancel — end the subscription
- Resume — restart a paused subscription