Subscriptions in Stripe

This chapter follows Webhooks in Stripe.

Subscriptions connect a Customer to one or more recurring Prices. Stripe creates Invoices each cycle, attempts payment with the default payment method, and emits Events your app uses to grant or revoke access.

Checkout in subscription mode

The fastest path mirrors one-time Checkout—set mode: 'subscription' and pass recurring Price ids:

1
import { stripe } from '../stripe-client.js';
2
import { usersById } from '../store.js';
3

4
const BASE_URL = process.env.BASE_URL ?? 'http://localhost:4242';
5

6
export async function createSubscriptionCheckout(req, res) {
7
  const { userId, priceId } = req.body;
8
  const user = usersById.get(userId);
9
  if (!user) return res.status(404).json({ error: 'Unknown user' });
10

11
  const session = await stripe.checkout.sessions.create({
12
    mode: 'subscription',
13
    customer: user.stripeCustomerId,
14
    line_items: [{ price: priceId, quantity: 1 }],
15
    success_url: `${BASE_URL}/success.html?session_id={CHECKOUT_SESSION_ID}`,
16
    cancel_url: `${BASE_URL}/cancel.html`,
17
    client_reference_id: userId,
18
    subscription_data: {
19
      trial_period_days: 14,
20
      metadata: { appUserId: userId },
21
    },
22
  });
23

24
  res.json({ url: session.url });
25
}

After Checkout, retrieve session.subscription or listen for customer.subscription.created in your webhook handler.

Subscription lifecycle and statuses

stateDiagram-v2
  [*] --> incomplete: create
  incomplete --> active: first payment succeeds
  incomplete --> incomplete_expired: timeout
  active --> past_due: payment fails
  past_due --> active: payment recovers
  past_due --> canceled: dunning exhausted
  active --> canceled: cancel at period end
  trialing --> active: trial ends with payment
  trialing --> canceled: cancel during trial

Store subscription.id and status on your user record; refresh from webhooks, not from the success page alone.

Invoices and recurring payment

Each billing period Stripe generates an Invoice and attempts automatic collection. Handle:

• invoice.paid — Extend entitlement for the new period.
• invoice.payment_failed — Notify the customer; Stripe retries based on your Dashboard smart retries settings.

1
function onInvoicePaid(invoice) {
2
  const subscriptionId = invoice.subscription;
3
  console.log('Subscription paid', subscriptionId, invoice.period_end);
4
}

Upgrades, downgrades, and proration

Change items on an existing subscription:

1
const subscription = await stripe.subscriptions.retrieve('sub_...');
2
await stripe.subscriptions.update(subscription.id, {
3
  items: [
4
    { id: subscription.items.data[0].id, price: 'price_new_plan' },
5
  ],
6
  proration_behavior: 'create_prorations',
7
});

Proration credits unused time and charges the new plan proportionally. Choose none when swapping at period boundaries only. Expose plan changes through your UI or the Customer Portal.

Cancellation

Cancel immediately or at period end:

1
await stripe.subscriptions.update('sub_...', {
2
  cancel_at_period_end: true,
3
});

Webhook customer.subscription.updated reflects cancel_at_period_end; customer.subscription.deleted fires when the subscription ends.

Customer Portal

Enable the Customer Portal in Dashboard settings so customers update payment methods, view invoices, and cancel without custom pages. Create a portal session on the server:

1
const portal = await stripe.billingPortal.sessions.create({
2
  customer: user.stripeCustomerId,
3
  return_url: `${BASE_URL}/account.html`,
4
});
5
res.json({ url: portal.url });

Portal configuration controls which Prices customers can switch to—keep it aligned with your public catalog.

Next: Stripe beyond payments.