Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 38 ยท Subscriptions and Billing

The Subscription Lifecycle: Trials, Renewals, Cancellation

Understand Stripe Subscriptions end to end: creating one with Checkout, every status from trialing to canceled, trial periods, renewals, cancel at period end, pausing and syncing access to your app.

A Subscription (sub_...) is Stripe's agreement to bill a customer for one or more recurring prices on a schedule. Each cycle, Stripe generates an invoice, tries to collect payment using the customer's default payment method, and updates the subscription's status. Your job is to keep your product's access in step with that status. Handled well, recurring revenue runs on its own; handled badly, you give free service to people whose cards failed, or lock out paying customers.

Creating a subscription

The simplest route is Checkout in subscription mode. It collects the card, applies SCA, creates the customer and the subscription, and returns the customer to your site.

JavaScript
// Real Stripe usage (read-only).
const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: proPriceId, quantity: 1 }],
  customer: user.stripeCustomerId,
  subscription_data: { trial_period_days: 14 },
  success_url: "https://example.com/welcome?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: "https://example.com/pricing",
});

You can also call stripe.subscriptions.create({ customer, items: [{ price }] }) directly for a customer who already has a saved, authenticated payment method (see Customers and Saved Payment Methods).

The statuses

Status Meaning Give access?
trialing In a free trial Yes
active Paid up Yes
past_due Latest invoice unpaid; Stripe is retrying Usually yes, with a warning banner
unpaid Retries exhausted (if configured to stop, not cancel) No
canceled Ended; cannot be revived No
incomplete First payment not yet successful (e.g. needs 3DS) No
incomplete_expired First payment never completed within 23 hours No
paused Collection paused (trial ended with no method, or you paused it) No
stateDiagram-v2
  [*] --> incomplete: created, first payment pending
  incomplete --> active: payment succeeds
  incomplete --> incomplete_expired: not paid in 23h
  [*] --> trialing: created with a trial
  trialing --> active: trial ends, payment ok
  trialing --> paused: trial ends, no card
  active --> past_due: renewal fails
  past_due --> active: retry succeeds
  past_due --> unpaid: retries exhausted
  past_due --> canceled: retries exhausted (cancel setting)
  active --> canceled: cancelled
  unpaid --> active: customer pays the invoice
  unpaid --> canceled

The subscription follows the outcome of its latest invoice.

A subscription's life

Trial Free days
Active Billed every cycle
Past due Payment failed, retrying
Canceled Ended for good
1 / 2

Mapping status to access

The decision "can this user use the product?" is a pure function of the subscription's status (and perhaps its end date). Keep it in one place so every part of your app agrees.

Node.js From status to access (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

(In the real API, a subscription that the customer cancels "at period end" stays active with cancel_at_period_end: true until the period finishes, then turns canceled. The stand-in above simplifies by keeping the end date on a canceled snapshot.)

Trials

A trial lets people try before paying. Configure it with trial_period_days or an exact trial_end. Two designs exist:

  • Card up front: Checkout collects the card and Stripe charges automatically when the trial ends. Higher conversion from trial to paid, fewer signups.
  • No card: set payment_method_collection: "if_required"; on trial end, if no method exists the subscription pauses (or cancels, by your choice) and you email the user to add one.

Stripe sends a customer.subscription.trial_will_end webhook three days before the trial ends: use it to remind customers. Send the reminder; surprise charges cause disputes.

Renewals and cancelling

Each cycle runs automatically. To end a subscription you pick one of two moves:

  • Cancel at period end (cancel_at_period_end: true): the customer keeps what they paid for until the period closes, and no further invoice is created. This is the friendly default for self-service cancellation, and it can be undone before the end.
  • Cancel immediately (stripe.subscriptions.cancel): ends right now. You can choose to refund the unused time via prorations (see Invoices and Proration).

You can also pause collection (pause_collection), keeping the subscription but not charging for a while, or schedule changes in advance using Subscription Schedules, for example "switch to the annual plan on 1 January".

Staying in sync: webhooks drive everything

Your database should mirror Stripe, and webhooks keep it correct. The events that matter most:

  • checkout.session.completed: link customer and subscription to your user.
  • customer.subscription.created / updated / deleted: copy the status and period end.
  • invoice.paid and invoice.payment_failed: money events (see the dunning lesson).

On each event, overwrite your stored copy from the object in the event (or re-fetch it) rather than applying relative changes, so out-of-order delivery cannot corrupt state.

Node.js Mirror events into your database (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Next, the documents and arithmetic behind every renewal: Invoices and Proration.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A subscription's renewal payment fails and Stripe is retrying. Which status is it in?

    past_due means the latest invoice is unpaid and retries are ongoing.
  2. 2. What does cancel_at_period_end: true do?

    It is the friendly cancellation: no new invoices, but access until the end of the paid period.
  3. 3. Why overwrite your stored subscription from the event's object instead of applying a delta?

    Snapshots are idempotent; relative changes can be applied twice or in the wrong order.
  4. 4. Which webhook lets you remind customers before a trial turns into a paid plan?

    Stripe sends it three days before the trial ends.

Summary

  • A Subscription bills recurring prices through invoices and moves through statuses: incomplete, trialing, active, past_due, unpaid, paused, canceled.
  • Decide access with one function of status, and warn on past_due.
  • Trials can require a card up front or not; remind customers before they end.
  • Cancel at period end for friendliness; cancel immediately only when needed.
  • Mirror state from webhook snapshots, ignoring stale and duplicate events.

Next: Invoices and Proration