Native Subscriptions

Lifecycle state machine

Every state, every transition — handled.

A subscription is a state machine, not a row you poll. Throttle owns the transitions: trial conversion, renewals, pause and resume, dunning, and cancellation. You react to events; the engine keeps the state.

trialing No charge yet

trial ends

active Renews each period ↻ renew

3 failed charges

past_due In dunning

dunning_exhausted

cancelled Terminal

paused ⇄ pause / resume from active

Cancel from any state — immediately, or scheduled for period end.

Built-in dunning

A failed charge isn't lost revenue.

When a renewal fails, Throttle retries automatically — on day 1, day 3, and day 7. If all three fail, the subscription cancels cleanly with reason dunning_exhausted. No silent leak. No recovery flow for you to build. No third-party rental.

Every attempt emits an event, so your backend — and your customer — always knows where things stand.

DAY 1retry

DAY 3retry

DAY 7retry

EXHAUSTEDclean cancel

Card captured up front

Trials start in trialing with no charge — but the card is vaulted at checkout. When the trial ends, the first invoice bills automatically. No "add a card to continue" friction, no dunning on day one.

Trial-fraud protection

Because the card is on file before the trial starts, repeat-trial abuse gets caught — a blocked attempt emits subscription.trial_blocked instead of silently minting free access.

Server SDK · @usethrottle/subscriptions

Full lifecycle control, server-side.

Drive every transition from your backend with a typed client — or call the same operations directly over the REST API. Same engine either way.

server.ts

import { createSubscriptionsClient } from '@usethrottle/subscriptions/server'

const subs = createSubscriptionsClient({
  apiKey: process.env.THROTTLE_SECRET_KEY,
})

// Full lifecycle — typed, server-side
await subs.pause(id)
await subs.resume(id)
await subs.changePlan({ id, planReference: 'pro_annual' })
await subs.cancel(id, { atPeriodEnd: true })

Or hit the REST API directly

POST /api/v1/subscriptions
GET /api/v1/subscriptions/:id
PATCH /api/v1/subscriptions/:id
POST /api/v1/subscriptions/:id/pause
POST /api/v1/subscriptions/:id/resume
POST /api/v1/subscriptions/:id/change-plan
POST /api/v1/subscriptions/:id/cancel

Events & webhooks

A webhook for every meaningful moment.

Thirteen subscription events, delivered to your endpoint with retries. Your backend stays in sync without polling.

subscription.created A subscription was created.

subscription.activated Trial ended or signup cleared — billing begins.

subscription.renewed A new period was charged successfully.

subscription.updated Subscription fields changed.

subscription.plan_changed Plan swapped — next renewal bills the new amount.

subscription.plan_change_scheduled A plan change is queued for period end.

subscription.paused Billing paused.

subscription.resumed Billing resumed.

subscription.past_due A renewal failed — dunning has started.

subscription.payment_failed A renewal attempt failed.

subscription.cancelled Cancelled — immediately or at period end.

subscription.create_failed Subscription creation failed.

subscription.trial_blocked A trial was blocked by fraud protection.

What ships in v1

Honest about the edges.

We'd rather tell you the boundary than have you find it in production.

In the box today

Recurring, prepaid & build-a-box billing
Trials with card-on-file + fraud protection
Automatic dunning (day 1 · 3 · 7 → clean cancel)
Pause, resume, plan change, cancel
The full 13-event webhook stream

Not yet

Usage-based metering
Mid-period proration
Seat / feature entitlements
Tiered, volume & sales-band pricing
Self-serve buyer portal (cancel · update card · invoices)

Flat or simply-recurring plans — consumer or SaaS — fit today, native to your commerce stack. Pricing on usage, seats, or sales bands, or a Stripe-style self-serve customer portal? Those aren't here yet — talk to us first and we'll tell you straight whether the fit is there.

Recurring revenue that doesn't leak.