Subscriptions

How a one-time checkout becomes recurring billing, what the renewal cron and dunning actually do, and the one gap to plan around before launching.

A subscription reuses the card vaulted during checkout to bill on a schedule. The buyer pays once through the embed; everything after that is Throttle charging the stored card and telling you what happened.

How billing runs

A cron sweeps for subscriptions due to renew and charges the vaulted card. A renewal either succeeds — producing an invoice and a subscription.renewed event — or it fails and enters dunning.

Dunning retries on a schedule rather than giving up on the first decline, since most failures are temporary: an expired card, a hold, a bank declining an unfamiliar merchant. Each retry re-evaluates usage and tier, so a retry bills the correct amount rather than the amount that was correct when the first attempt failed.

If a backup payment method is on file, Throttle falls back to it and tells you it did.

Changing a subscription

ActionEffect
Pause / resumeStops and restarts billing without losing the subscription
CancelEnds it, optionally at period end
Change planMoves to a different price, with proration
Change quantitySeat count up or down, with proration

Plan and quantity changes take an effective choice: now applies immediately and prorates, or period_end queues the change for the next cycle. A queued change can be withdrawn before it lands.

Proration is calculated and returned on the response, so you can show the buyer the exact figure before committing.

Selling goods alongside a plan

One checkout can sell goods and up to ten subscriptions together — a plan plus a starter kit, two different plans, or the same plan twice. Throttle charges everything in one capture with one shipping fee, and the order links to every subscription it created: the plans are granted immediately, the goods stay yours to ship.

Each subscription renews on its own schedule and bills its plan alone. The goods never repeat, and renewals never charge shipping. The integration details are in Mixed carts.

Usage-based billing

Report metered usage against the current billing period and it bills on top of the base amount at the next renewal. Usage items are overage, not add-ons: a subscription is one plan times a quantity, plus whatever usage you reported. There is no concept of multiple recurring sub-items on one subscription.

Trials

A subscription can start with a trial. Throttle runs a card-fingerprint check that catches the same physical card being reused across “fresh” accounts — automatically inside the auto-create flow, and available as a pre-flight endpoint if you want to check before showing a trial offer.

Webhooks are the source of truth

Subscription state changes reach you as events. Do not poll, and do not infer state from the last API response you happened to make — a renewal that succeeds at 3am is a webhook, not something your code asked for.

Payloads carry the full customer object, including both external identifiers, so you can match the buyer to your own records without a lookup per event.

The gap to plan around

Buyers cannot manage their own subscriptions. Every mutation is merchant-scoped. There is no hosted page where a buyer cancels, pauses, or updates a card.

The sharp edge: a dunning email tells the buyer to update their payment method, and there is nowhere to send them. If you are launching subscriptions, budget for building that surface against the API — otherwise every failed renewal becomes a support conversation.

Discounts apply to the first charge only

A discount code on a recurring checkout discounts the signup charge. Renewals bill the full plan price, so “20% off your first month” works and “first three months off” does not — a multi-period promotion has to be modelled as a different plan, or handled outside Throttle.

Because the discount must not leak into renewals, the session-level recurring intent has to state the real renewal price: pass recurring.amount alongside the code, or session creation is rejected rather than quietly discounting every future cycle. A subscription line carries its own price, so it needs nothing extra.

  • What Throttle stores — The objects Throttle owns, the one thing it deliberately does not store, and how workspace, application, and environment scope everything else.
  • Refunds and returns — Four ways to give a buyer their money back — refund, cancel, return, or exchange — and which one fits the situation you are actually in.
  • Discounts — Percentage and fixed-amount promotion codes: the limits you can put on them, the nine reasons a code gets rejected, and how product scoping matches.

Last updated September 29, 2026