Subscription lifecycle

The unified status model, scheduled cancellations, entitlement checks, every lifecycle operation, and the per-provider proration matrix.

Subscriptions are where billing providers disagree most: each has its own status vocabulary, and most of them overload one status to mean both “canceled, access ended” and “canceled, but still paid up until the end of the period”. revenue-sdk normalizes all of it into one seven-value status enum plus one boolean.

The unified status model

type SubscriptionStatus =
  | 'incomplete'
  | 'trialing'
  | 'active'
  | 'past_due'
  | 'unpaid'
  | 'paused'
  | 'canceled';

Per-provider mapping

A dash means the provider has no equivalent state. Unrecognized provider statuses fall back to active so a newly introduced status never breaks an entitlement check silently — inspect raw if you need the exact provider value.

canceled is terminal — cancelAtPeriodEnd is the schedule

This is the decision that makes the model work: a scheduled cancellation is not a status. When a customer cancels, the subscription keeps its current status (active or trialing) and gains:

• cancelAtPeriodEnd: true
• endsAt — the date access actually ends

Only when that date passes does the status become canceled. So:

subscription.status === 'canceled'; // access has ended, permanently
subscription.cancelAtPeriodEnd; // will not renew, but is still paid up

How cancelAtPeriodEnd is detected

Once a subscription is terminally canceled, cancelAtPeriodEnd is forced back to false — there is nothing left to schedule.

A lifecycle timeline

// status: 'active' (or 'trialing' when the price has a trial)
// cancelAtPeriodEnd: false
// currentPeriodEnd: 2026-09-01

const subscription = await client.subscriptions.cancel({ id });
// status: 'active'          ← unchanged
// cancelAtPeriodEnd: true
// endsAt: 2026-09-01

const subscription = await client.subscriptions.uncancel({ id });
// status: 'active'
// cancelAtPeriodEnd: false
// endsAt: undefined

// status: 'canceled'        ← terminal
// cancelAtPeriodEnd: false
// endedAt: 2026-09-01

Checking entitlement

The whole point of the model is that entitlement is a two-line check that works on every provider:

import type { Subscription } from 'revenue-sdk';

const ENTITLED: ReadonlySet<Subscription['status']> = new Set(['active', 'trialing']);

export function isEntitled(subscription: Subscription): boolean {
  return ENTITLED.has(subscription.status);
}

Note what is not in the check: cancelAtPeriodEnd is irrelevant to access. A subscription scheduled to cancel is still paid for and still entitled until it flips to canceled.

Optional past_due grace

past_due means a renewal failed and the provider is retrying. Whether you keep access on during the dunning window is a product decision — most SaaS products do, to avoid punishing an expired card:

const GRACE: ReadonlySet<Subscription['status']> = new Set(['active', 'trialing', 'past_due']);

export function isEntitled(subscription: Subscription, allowGrace = true): boolean {
  return (allowGrace ? GRACE : ENTITLED).has(subscription.status);
}

Do not extend the grace to unpaid (retries exhausted) or paused (deliberately suspended).

Surfacing the end date

if (subscription.cancelAtPeriodEnd && subscription.endsAt) {
  banner(`Your plan ends on ${subscription.endsAt.toLocaleDateString()}.`);
}

endsAt is “when access ends” — the effective date of a scheduled cancellation, or the end of a grace period. endedAt is “when it actually terminated”, and is only set once the subscription is over.

Lifecycle operations

Cancel at period end

const subscription = await client.subscriptions.cancel({
  id: 'SUBSCRIPTION_ID',
  reason: 'too_expensive', // requires the cancellationReason capability
  comment: 'Moving to the annual plan elsewhere',
});

reason is one of customer_service, low_quality, missing_features, other, switched_service, too_complex, too_expensive, unused. Passing reason or comment to a provider without the cancellationReason capability (Lemon Squeezy, Paddle) throws unsupported — omit them for provider-agnostic code.

Revert a scheduled cancellation

const subscription = await client.subscriptions.uncancel({ id: 'SUBSCRIPTION_ID' });

Supported by all five providers. It only reverts a scheduled cancellation — a terminally canceled subscription cannot be resurrected; create a new checkout instead.

Change plan

const subscription = await client.subscriptions.changePlan({
  id: 'SUBSCRIPTION_ID',
  product: yearlyPrice.checkoutRef,
  quantity: 1,
  prorationBehavior: 'prorate',
});

product is a Price.checkoutRef, not a Product.id. Polar and Lemon Squeezy reject a quantity other than 1.

End a trial early

const subscription = await client.subscriptions.endTrial({ id: 'SUBSCRIPTION_ID' });

Bills the customer immediately and starts the paid cycle. Dodo Payments has no such operation and throws unsupported.

Revoke immediately

const subscription = await client.subscriptions.revoke({ id: 'SUBSCRIPTION_ID' });
// status: 'canceled', access ends now

Terminates the subscription right away, with no remaining access. Lemon Squeezy cannot do this and throws unsupported — its cancel always runs to the end of the period.

Proration behaviors

prorationBehavior controls what happens to the money when a plan changes mid-period:

Support and wire mapping per provider:

Polar has no equivalent of none: its next_period mode defers the plan change itself and reset restarts the billing anchor — neither matches “switch now, bill nothing extra”, so the SDK refuses rather than pick a lookalike. Dodo Payments has no defer-to-next-invoice mode, so prorate is refused.

The client checks prorationBehavior against capabilities.prorationBehaviors before the request:

if (client.capabilities.prorationBehaviors.includes('none')) {
  await client.subscriptions.changePlan({ id, product, prorationBehavior: 'none' });
}

The Subscription model

Listing subscriptions

const { items, cursor } = await client.subscriptions.list({ customerId: 'CUSTOMER_ID' });

The customerId filter requires the listSubscriptionsByCustomer capability — Lemon Squeezy cannot filter by customer and throws unsupported (it filters by store, product, variant, or email instead).