Plans and Subscriptions
Plans
A Plan represents a pricing tier your product offers. Each plan defines:
- Name and description — shown to users at signup and on invoices
- Price — flat rate or per-seat; monthly or annual billing periods
- Features — a list of named capabilities included in the plan
- Quotas — usage limits (e.g., 10 GB storage, 1 000 API calls/month)
- Currency overrides — per-country/region pricing if you need geo-based pricing
Free Plans
Plans with a price of 0 are treated as free plans. Users can subscribe to a free
plan without entering payment details.
Trial Plans
Trial subscriptions have a defined end date. When the trial expires, the subscription
moves to expired status and access is revoked unless the user upgrades.
Plan Visibility
Plans can be public (visible in your pricing page) or unlisted (accessible only via direct link or API, useful for custom or legacy pricing).
Subscriptions
A Subscription represents a user's active entitlement to a plan during a specific billing period.
Subscription Statuses
| Status | Meaning |
|---|---|
active | Access is granted and the subscription is current |
trialing | In a free trial period |
past_due | Renewal payment has failed; access may be restricted |
canceled | User cancelled; access continues until the period end date |
expired | Period has ended and access has been revoked |
upgraded | Replaced by a newer, higher-tier subscription |
downgraded | Replaced by a lower-tier subscription at next renewal |
paused | Temporarily suspended (not currently available in the public API) |
Purchasing a Subscription
- The user selects a plan and navigates to checkout.
- They pick a billing account and payment method.
- Payment is collected. On success, a subscription is created and quotas are activated.
- An invoice is generated and emailed to the billing contact.
Auto-Renewal
Subscriptions renew automatically by default at the end of each billing period. When auto-renewal runs:
- A new subscription record is created for the new cycle.
- The previous subscription is marked
completed. - Remaining quota (unused capacity) from the old cycle is carried forward.
- The renewal is charged to the saved payment method on the subscription.
You can set a per-subscription renewal payment method separately from the billing account's default method.
Cancellation
Cancelling a subscription stops auto-renewal. Access continues until the current
period ends, at which point the subscription moves to expired. Cancellation is
immediate in terms of stopping future charges — there is no partial-period refund
by default (check the product's refund policy).
Upgrading
When a user upgrades to a higher-tier plan:
- The current subscription is marked
upgraded. - A new subscription for the new plan starts immediately.
- Remaining quota balance is carried over (pro-rated by time remaining).
- The user is charged the difference for the remainder of the current period.
Downgrading
When a user downgrades to a lower-tier plan:
- The current subscription stays active until its period end.
- A new subscription for the lower-tier plan is queued.
- It activates automatically when the current period expires.
Seat-Based Pricing
For seat-based plans, the subscription price is pricePerSeat × seatCount. Seats
can be added or removed at any time; the subscription amount is updated accordingly
and a prorated charge or credit may apply.
Coupons and Promotions
Coupon codes can be applied at checkout to receive a discount. Coupons may offer:
- A percentage discount (e.g., 20% off)
- A fixed amount discount (e.g., $10 off)
Coupons have validity windows and usage limits. An expired or fully-used coupon is rejected at checkout with a clear error message. Coupon codes are case-insensitive and single-use per user by default unless configured otherwise.