Subscriptions
Recurring billing for merchants. Create a subscription plan, attach subscribers (clients) to it, and let the platform handle renewal invoicing.
Concepts
A plan defines what is billed: price, currency, items, and renewal interval (e.g., 1 month). It is created once and reused across many subscribers.
A subscriber is a client identified by email and attached to a specific plan. The platform issues a renewal invoice for each subscriber on every cycle, tracks per-subscriber and per-plan revenue, and exposes endpoints to activate, deactivate, and inspect billing history.
Lifecycle
| # | What happens | Method | Endpoint |
|---|---|---|---|
| 1 | Merchant creates a plan | POST | /api/subscriptions |
| 2 | Merchant attaches subscribers by email (one or many) | POST | /api/subscriptions/:id/users |
| 3 | Platform issues an invoice and emails the subscriber a Pay Now link | — | standard invoice flow |
| 4 | Subscriber pays before the invoice expires → status becomes active | — | — |
| 5 | Merchant can deactivate / reactivate a subscriber at any time | POST | .../deactivate · .../activate |
Subscriber Statuses
Status applies to each subscriber's membership in a plan; plans themselves do not currently carry a status.
| Status | Meaning |
|---|---|
active | Subscriber is billed on each renewal cycle. |
pending | Subscriber is awaiting the first successful payment to become active. New subscribers start here. |
inactive | Subscriber is paused. No renewal invoices are generated for them until reactivation. |
Renewal Invoices
Renewal invoices are ordinary invoices — they use the same payload structure (Get Regular Invoice Info), move through the same statuses, and fire the same Invoice Webhooks with no subscription-specific fields.
The current version targets a 1-month billing period. A renewal invoice is issued 4 days before the period ends and stays payable until 3 days after — a 7-day window — after which it becomes expired. When a subscriber pays within that window, their status flips to active.
Two endpoints expose invoice history:
- List Plan Invoices — all invoices generated by a plan, across subscribers.
- List Subscriber Invoices — invoices for a single subscriber on a plan.