Managing Subscriptions

A subscription is not a single charge — it is an ongoing relationship that lives in time. It has a status, a current period, and a billing schedule that the provider advances automatically.

Your job is to mirror that state in your own database so your app always knows whether a given user is currently entitled to paid features.

A subscription moves through states: trialing, active, past_due, canceled, and unpaid. Each transition has consequences for access.

Model this explicitly. Treat "active" and "trialing" as entitled, "past_due" as a grace window, and "canceled" or "unpaid" as revoked. Hard-coding a single boolean throws away information you will need.

Resist sprinkling "if user.paid" everywhere. Centralize a single function that answers "what is this user entitled to right now?" based on their subscription state.

This entitlement check becomes the one place your access logic lives. Change a rule once and the whole app obeys it.

A trial grants access before the first charge. The subscription exists in a trialing state; at trial end the provider attempts payment and flips to active or past_due.

Decide whether trials require a card up front. Card-up-front reduces abuse but lowers signups; card-free is friendlier but invites tire-kickers.

Customers switch plans mid-cycle. Upgrades usually take effect immediately with a prorated charge for the remaining period. Downgrades often apply at the next renewal to avoid refunds.

Proration is the math of crediting unused time and billing the difference. Let the provider compute it; your job is to choose the timing policy.

Cancelling rarely means instant cutoff. The standard pattern is cancel_at_period_end: the user keeps access until the period they already paid for runs out, then it lapses.

This avoids refund disputes and respects what the customer paid for. Reflect both the cancellation request and the actual lapse in your state.

Cards expire and fail. When a renewal fails, the subscription goes past_due and the provider retries on a schedule — this recovery process is called dunning.

During dunning you can keep access (grace) or restrict it. Send the customer emails to update their card. Decide your grace policy explicitly.

The provider is the source of truth, but querying it on every request is slow. Instead, cache the subscription state in your database and update it whenever a webhook arrives.

Every relevant event — created, updated, deleted, payment_failed — should write the new status to your record. Your app then reads its own fast, local copy.

Building a self-service billing UI is a lot of work. Most providers offer a hosted customer portal where users update cards, switch plans, view invoices, and cancel.

You generate a portal link from your server; the provider handles the rest and emits webhooks for any changes the user makes. This saves weeks of UI work.

Real life is messy: a past_due user pays late and should regain access; a canceled user resubscribes; a refund reverses a charge. Each must update entitlements correctly.

Drive every change through the same status-to-entitlement logic. If reactivation flips status back to active, access should restore automatically with no special-case code.

Use test clocks or simulated events to fast-forward time: start a trial, end it, fail a renewal, recover, then cancel. Verify entitlements at every step.

Subscriptions fail in the future, not at checkout. Testing the full lifecycle is the only way to catch a renewal bug before a customer does.

Confirm the cleanest way to manage access logic.

Subscriptions are stateful relationships with a status machine: trialing, active, past_due, canceled, unpaid. Centralize access in one entitlement function so every gate obeys the same rule, and cache provider state in your DB via webhooks instead of polling.

Handle trials, prorated upgrades, period-end cancellations, and dunning for failed renewals. Offer a hosted customer portal to save UI work, and test the entire lifecycle with test clocks before launch.