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.

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 do not apply

Discount codes are rejected on recurring checkout sessions, so “first three months off” is not expressible today. A promotional first period has to be modelled as a different plan, or handled outside Throttle.

  • 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.

Last updated August 9, 2026