Subscriptions

Recipe

Create subscription products and prices in Stripe, then use Checkout Sessions or PaymentIntents to subscribe customers. Manage subscription lifecycle with the Customer Portal and webhooks.

Create a subscription via Checkout Session:

// app/actions/subscribe.ts
"use server";
 
import { stripe } from "@/lib/stripe";
import { redirect } from "next/navigation";
 
export async function createSubscriptionCheckout(priceId: string) {
  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
    subscription_data: {
      trial_period_days: 14,
    },
  });
 
  redirect(session.url!);
}

Or create a subscription directly via the API:

// app/actions/subscribe-direct.ts
"use server";
 
import { stripe } from "@/lib/stripe";
 
export async function createSubscription(
  customerId: string,
  priceId: string
) {
  const subscription = await stripe.subscriptions.create({

Working Example

// app/pricing/page.tsx
import { stripe } from "@/lib/stripe";
import { createSubscriptionCheckout } from "@/app/actions/subscribe";
 
interface PricingTier {
  name: string;
  priceId: string;
  price: number;
  interval:

Deep Dive

How It Works

• Stripe subscriptions are built on three objects: Product (what you sell), Price (how much and how often), and Subscription (a customer's active plan).
• Products and Prices can be created in the Stripe Dashboard or via the API. Each Price has an interval (day, week, month, year) and an amount.
• When using Checkout with mode: "subscription", Stripe creates the Customer, Subscription, and handles the first payment automatically.
• When using the API directly with payment_behavior: "default_incomplete", the subscription starts in an incomplete state until the first payment is confirmed client-side.
• Subscription statuses flow through: trialing (if trial set) then active, past_due (payment failed), canceled, or unpaid.
• Trial periods delay the first charge. During a trial, the subscription status is trialing and no invoice is generated until the trial ends.

Variations

Annual vs monthly pricing:

// Create both prices for the same product
const monthlyPrice = await stripe.prices.create({
  product: "prod_xxx",
  unit_amount: 2900,
  currency: "usd",
  recurring: { interval: "month" },
});
 
const annualPrice = await stripe.prices.create({

Cancel a subscription:

// Cancel at end of billing period
await stripe.subscriptions.update(subscriptionId, {
  cancel_at_period_end: true,
});
 
// Cancel immediately
await stripe.subscriptions.cancel(subscriptionId);

Update subscription (change plan):

const subscription = await stripe.subscriptions.retrieve(subscriptionId);
 
await stripe.subscriptions.update(subscriptionId, {
  items: [
    {
      id: subscription.items.data[0].id,
      price: newPriceId,
    },
  ],
  proration_behavior: "create_prorations",
});

TypeScript Notes

• stripe.subscriptions.create returns Promise<Stripe.Subscription>.
• When using expand, the expanded fields change types. Cast explicitly after expansion.
• Subscription status is a union type: "active" | "past_due" | "canceled" | "incomplete" | "incomplete_expired" | "trialing" | "unpaid" | "paused".

import type Stripe from "stripe";
 
function isActive(subscription: Stripe.Subscription): boolean {
  return subscription.status === "active" || subscription.status === "trialing";
}

Gotchas

• Never grant access based solely on a successful Checkout redirect. Always verify subscription status via webhooks (customer.subscription.created, invoice.paid).
• When using payment_behavior: "default_incomplete", you must confirm the PaymentIntent client-side or the subscription stays incomplete and expires after 23 hours.
• Proration happens by default when changing plans mid-cycle. Set proration_behavior: "none" to disable it.
• cancel_at_period_end: true does not immediately cancel. The subscription stays active until the current period ends. Listen for customer.subscription.deleted to revoke access.
• Trial periods created via Checkout require payment_method_collection: "if_required" if you do not want to collect a card upfront. The default collects a card.
• Stripe creates a $0 invoice at trial start. This is normal and expected.

Alternatives

FAQs

// End of period (subscription stays active until period ends)
await stripe.subscriptions.update(subId, {
  cancel_at_period_end: true,
});
 
// Immediately
await stripe.subscriptions.cancel(subId);

await stripe.prices.create({
  product: "prod_xxx",
  unit_amount: 2900,
  currency: "usd",
  recurring: { interval: "month" },
});
await stripe.prices.create({
  product: "prod_xxx",
  unit_amount: 29000,

import type Stripe from "stripe";
 
function isActive(sub: Stripe.Subscription): boolean {
  return sub.status === "active" || sub.status === "trialing";
}

const invoice = subscription.latest_invoice as Stripe.Invoice;
const pi = invoice.payment_intent as Stripe.PaymentIntent;

Related Links

• Stripe Subscriptions Guide
• Subscription Lifecycle
• Trial Periods
• Prorations