Subscriptions
Subscriptions link users to plans with lifecycle state. API endpoints: HTTP API → Subscriptions.
Lifecycle
Subscriptions support trials (trial_days or trial_ends_at), pause, resume,
and cancel-at-period-end.
Plan change policies
| Policy | Behavior |
|---|---|
prorate_immediately | Plan changes now; billing period preserved; separate adjustment.posted (kind: prorate) records the delta |
refund_immediately | Old period closed; new period starts; separate refund.issued records credit for unused time |
effective_next_cycle | Change queued until period boundary |
Resume after pause does not rewrite history: if the trial is still active, the subscription returns to trialing according to the original schedule; otherwise a new billing period starts at
resume time. Paused time is excluded from the base fee in the invoice.