Skip to main content

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​

StatusMeaning
activeAccess is granted and the subscription is current
trialingIn a free trial period
past_dueRenewal payment has failed; access may be restricted
canceledUser cancelled; access continues until the period end date
expiredPeriod has ended and access has been revoked
upgradedReplaced by a newer, higher-tier subscription
downgradedReplaced by a lower-tier subscription at next renewal
pausedTemporarily suspended (not currently available in the public API)

Purchasing a Subscription​

  1. The user selects a plan and navigates to checkout.
  2. They pick a billing account and payment method.
  3. Payment is collected. On success, a subscription is created and quotas are activated.
  4. 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.