This guide covers the complete Stripe subscription integration for Next.js — from first install to production-ready webhook handling, Customer Portal, and failed payment recovery. Key takeaways: - Stripe is the source of truth for all billing data. Never store subscription prices in your database. Sync status via webhooks. - Always pass `userId` in checkout session metadata. It's the only reliable way to link a Stripe customer to your user after checkout. - Never use `request.json()` in your webhook handler. You need the raw body to verify the Stripe signature. Use `request.text()`. - Webhooks guarantee at-least-once delivery. Make your handlers idempotent — processing the same event twice should be safe. - The Customer Portal handles upgrades, downgrades, and cancellations for you. Enable it and link to it. Don't build subscription management UI yourself. - For local development: `stripe listen --forward-to localhost:3000/api/stripe/webhook`. Test cards: `4242 4242 4242 4242` (success), `4000 0000 0000 0002` (decline).

## What Most Tutorials Miss Every Stripe + Next.js tutorial shows you how to create a checkout session. Few show you what happens after the user subscribes. That's where real SaaS products get broken. As Pedro Alonso — a product engineer who builds Stripe billing systems for SaaS teams professionally — notes: "Building a subscription-based service is an iterative process. Start with the basics, then gradually add more advanced features as your needs evolve. The edge cases in this post are the work I do every week." ([source](https://www.pedroalonso.net/blog/stripe-subscriptions-nextjs/)) The edge cases are what this guide is for. Here's the full lifecycle of a subscription over 12 months: | Event | Stripe webhook | Your responsibility | |---|---|---| | User subscribes | `checkout.session.completed` | Create customer record, grant access | | Monthly renewal | `invoice.payment_succeeded` | Log renewal, trigger email | | Card expires | `invoice.payment_failed` | Start dunning, update status to `past_due` | | User cancels | `customer.subscription.deleted` | Remove access at period end | | User upgrades | `customer.subscription.updated` | Sync new plan status | | Payment recovers | `invoice.payment_succeeded` | Restore active status | If your app doesn't handle each of these events, you'll have users with broken access, missed revenue, and no debugging trail. This guide covers the complete flow.

## Setup Install three packages. That's all you need: ```bash npm install stripe @stripe/stripe-js @stripe/react-stripe-js ``` - `stripe` — server-side SDK. Never ships to the browser. - `@stripe/stripe-js` — client-side library for redirecting to Checkout. - `@stripe/react-stripe-js` — React bindings for Stripe Elements (only needed if you build custom payment forms). **Environment variables:** ```bash # .env.local STRIPE_SECRET_KEY=sk_test_... # server only — no NEXT_PUBLIC_ prefix STRIPE_WEBHOOK_SECRET=whsec_... # server only NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_... # safe to expose in client ``` **Create a shared Stripe client — instantiate once, not per request:** ```ts // lib/stripe.ts import Stripe from "stripe"; export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2026-06-24.dahlia", // pin to a specific API version typescript: true, }); ``` Pin the API version. Stripe deploys breaking changes behind API version upgrades — pinning means you opt in to changes on your schedule, not Stripe's. **Database schema** — the minimum you need to sync subscription state: ```sql -- Add to your users table (or create a subscriptions table) ALTER TABLE users ADD COLUMN stripe_customer_id TEXT UNIQUE; ALTER TABLE users ADD COLUMN stripe_subscription_id TEXT UNIQUE; ALTER TABLE users ADD COLUMN subscription_status TEXT DEFAULT 'inactive'; -- active | trialing | past_due | canceled | inactive ALTER TABLE users ADD COLUMN subscription_period_end TIMESTAMPTZ; ```

## Creating Products and Prices in Stripe Before writing code, set up your products in the Stripe Dashboard → Product Catalog. One product can have multiple prices (monthly, annual, different tiers). The **Price ID** (`price_xxx`) is what you use in code — not the Product ID. Copy the Price IDs and put them in your app config: ```ts // lib/stripe-config.ts export const STRIPE_PLANS = { pro_monthly: { priceId: "price_xxx_monthly", name: "Pro", interval: "month", amount: 10_00, // $10.00 in cents }, pro_annual: { priceId: "price_xxx_annual", name: "Pro Annual", interval: "year", amount: 100_00, // $100.00 in cents }, } as const; export type PlanKey = keyof typeof STRIPE_PLANS; ``` **Never hardcode prices in your UI.** Pull them from this config so you have one place to update.

## Checkout: Creating a Subscription Session **The checkout session is how a user enters the Stripe billing flow.** Create it server-side via a Server Action — never client-side, or your secret key is exposed. Never create checkout sessions client-side — your secret key would be exposed. ```ts // app/actions/billing.ts "use server"; import { stripe } from "@/lib/stripe"; import { STRIPE_PLANS } from "@/lib/stripe-config"; import { headers } from "next/headers"; import { redirect } from "next/navigation"; import { getSession } from "@/lib/auth"; // your auth helper export async function createCheckoutSession(planKey: keyof typeof STRIPE_PLANS) { const session = await getSession(); if (!session?.user) redirect("/login"); const origin = (await headers()).get("origin")!; const plan = STRIPE_PLANS[planKey]; const checkoutSession = await stripe.checkout.sessions.create({ mode: "subscription", line_items: [{ price: plan.priceId, quantity: 1 }], success_url: `${origin}/dashboard?success=true`, cancel_url: `${origin}/pricing?canceled=true`, metadata: { userId: session.user.id, // CRITICAL — this is how you link Stripe to your user }, subscription_data: { metadata: { userId: session.user.id, // also add to subscription for webhook access }, }, // Pre-fill email if you have it customer_email: session.user.email, // Allow promotion codes allow_promotion_codes: true, }); redirect(checkoutSession.url!); } ``` Call it from a Client Component: ```tsx // app/pricing/page.tsx "use client"; import { createCheckoutSession } from "@/app/actions/billing"; import { useTransition } from "react"; export default function PricingPage() { const [isPending, startTransition] = useTransition(); return ( ); } ``` **Why `userId` in metadata matters:** After checkout, Stripe sends a `checkout.session.completed` webhook. The only way to know which user just paid is `metadata.userId`. Without it, you're manually cross-referencing customer emails — which breaks with name changes, multiple accounts, and test environments.

## Webhooks: The Most Important Part **Webhooks are the backbone of your billing system.** Without them your database never learns about renewals, failures, or cancellations — and users either lose access incorrectly or keep access after canceling. Getting this wrong means users can pay and not get access, or cancel and keep access. **Create the webhook handler:** ```ts // app/api/stripe/webhook/route.ts import { NextRequest, NextResponse } from "next/server"; import { stripe } from "@/lib/stripe"; import { headers } from "next/headers"; import { db } from "@/lib/db"; // CRITICAL: disable body parsing — Stripe signature verification requires raw body export const runtime = "nodejs"; // webhook handlers must run on Node.js, not Edge export async function POST(request: NextRequest) { const body = await request.text(); // NOT request.json() — must be raw text const headersList = await headers(); const signature = headersList.get("stripe-signature")!; let event: Stripe.Event; try { event = stripe.webhooks.constructEvent( body, signature, process.env.STRIPE_WEBHOOK_SECRET! ); } catch (err: any) { console.error("[webhook] signature verification failed:", err.message); return NextResponse.json({ error: "Invalid signature" }, { status: 400 }); } // Process events try { await handleStripeEvent(event); } catch (err) { console.error("[webhook] handler error:", err); // Return 500 so Stripe retries the event return NextResponse.json({ error: "Handler failed" }, { status: 500 }); } return NextResponse.json({ received: true }); } async function handleStripeEvent(event: Stripe.Event) { switch (event.type) { case "checkout.session.completed": { const session = event.data.object as Stripe.Checkout.Session; await handleCheckoutCompleted(session); break; } case "customer.subscription.updated": { const subscription = event.data.object as Stripe.Subscription; await syncSubscription(subscription); break; } case "customer.subscription.deleted": { const subscription = event.data.object as Stripe.Subscription; await handleSubscriptionCanceled(subscription); break; } case "invoice.payment_succeeded": { const invoice = event.data.object as Stripe.Invoice; await handlePaymentSucceeded(invoice); break; } case "invoice.payment_failed": { const invoice = event.data.object as Stripe.Invoice; await handlePaymentFailed(invoice); break; } default: // Ignore unhandled events break; } } ``` **The most common webhook mistake: `request.json()` instead of `request.text()`.** Stripe verifies its webhook payload using a HMAC signature of the raw request body. If you parse the body as JSON first, the raw bytes change and signature verification fails. Always use `request.text()`.

## Handling Each Subscription Event ```ts // app/api/stripe/webhook/handlers.ts async function handleCheckoutCompleted(session: Stripe.Checkout.Session) { const userId = session.metadata?.userId; if (!userId) { console.error("[webhook] checkout.session.completed: no userId in metadata"); return; } // Fetch the full subscription object const subscription = await stripe.subscriptions.retrieve( session.subscription as string ); await db.user.update({ where: { id: userId }, data: { stripeCustomerId: session.customer as string, stripeSubscriptionId: subscription.id, subscriptionStatus: subscription.status, subscriptionPeriodEnd: new Date(subscription.current_period_end * 1000), }, }); } async function syncSubscription(subscription: Stripe.Subscription) { const userId = subscription.metadata?.userId; if (!userId) return; await db.user.update({ where: { id: userId }, data: { subscriptionStatus: subscription.status, subscriptionPeriodEnd: new Date(subscription.current_period_end * 1000), }, }); } async function handleSubscriptionCanceled(subscription: Stripe.Subscription) { const userId = subscription.metadata?.userId; if (!userId) return; await db.user.update({ where: { id: userId }, data: { subscriptionStatus: "canceled", // Don't remove access immediately — let them use until period end subscriptionPeriodEnd: new Date(subscription.current_period_end * 1000), }, }); } async function handlePaymentSucceeded(invoice: Stripe.Invoice) { // Renewal payment — subscription already updated by customer.subscription.updated // Use this event to trigger renewal emails or analytics console.log("[billing] payment succeeded:", invoice.id); } async function handlePaymentFailed(invoice: Stripe.Invoice) { // Stripe will retry automatically based on your Smart Retries settings // This is where you trigger a "payment failed" email to the user const subscription = await stripe.subscriptions.retrieve( invoice.subscription as string ); const userId = subscription.metadata?.userId; if (!userId) return; // Send dunning email, update status to past_due await db.user.update({ where: { id: userId }, data: { subscriptionStatus: "past_due" }, }); // sendPaymentFailedEmail(userId); — trigger via Resend, Inngest, etc. } ``` **Idempotency matters.** Stripe guarantees at-least-once delivery — the same event can be delivered more than once. Your handlers must be safe to run multiple times. Using `update` (upsert by userId) rather than `create` is naturally idempotent. If you're doing something that should only happen once (like sending a welcome email), check if it's already happened before sending.

## Checking Subscription Status Never trust client-side state for access control. Check subscription status server-side on every protected request. ```ts // lib/subscription.ts import { db } from "@/lib/db"; export async function getSubscriptionStatus(userId: string) { const user = await db.user.findUnique({ where: { id: userId }, select: { subscriptionStatus: true, subscriptionPeriodEnd: true, }, }); if (!user) return { isActive: false }; const isActive = user.subscriptionStatus === "active" || user.subscriptionStatus === "trialing" || // Allow access until period end even after cancellation (user.subscriptionStatus === "canceled" && user.subscriptionPeriodEnd && user.subscriptionPeriodEnd > new Date()); return { isActive, status: user.subscriptionStatus }; } ``` Use this in Server Components, Server Actions, and API Routes: ```ts // In a Server Action export async function someProtectedAction() { const session = await getSession(); if (!session?.user) throw new Error("Not authenticated"); const { isActive } = await getSubscriptionStatus(session.user.id); if (!isActive) throw new Error("Active subscription required"); // ... rest of action } ``` For Supabase RLS, store subscription status in a column and create a policy that checks it. For middleware-based protection, check the database on each request and redirect to `/pricing` if inactive — but cache the result for a short window to avoid a database hit on every request.

## Customer Portal: Don't Build Subscription Management UI **The Customer Portal is Stripe's hosted subscription management page.** Enable it once in your dashboard, redirect users to it, and Stripe handles upgrades, downgrades, cancellations, payment method updates, and invoice history — upgrades, downgrades, cancellations, payment method updates, invoice history. Enable it in your Stripe Dashboard → Customer Portal settings, then create a session and redirect users to it. Don't build subscription management UI yourself. The Customer Portal handles it, including proration calculations for mid-cycle upgrades. ```ts // app/actions/billing.ts export async function createPortalSession() { const session = await getSession(); if (!session?.user) redirect("/login"); const user = await db.user.findUnique({ where: { id: session.user.id }, select: { stripeCustomerId: true }, }); if (!user?.stripeCustomerId) redirect("/pricing"); const origin = (await headers()).get("origin")!; const portalSession = await stripe.billingPortal.sessions.create({ customer: user.stripeCustomerId, return_url: `${origin}/dashboard/billing`, }); redirect(portalSession.url); } ``` Add a "Manage subscription" button that calls this action. When users cancel, upgrade, or update their payment method through the portal, Stripe sends webhook events and your handlers sync the change to your database automatically.

## Local Development and Testing **Forward webhooks to localhost with the Stripe CLI:** ```bash # macOS brew install stripe/stripe-cli/stripe # Windows (Scoop) scoop install stripe # Linux — see https://stripe.com/docs/stripe-cli for package manager options # Log in stripe login # Forward events to your local webhook handler stripe listen --forward-to localhost:3000/api/stripe/webhook ``` The CLI outputs a webhook signing secret starting with `whsec_`. Use this as `STRIPE_WEBHOOK_SECRET` in `.env.local` during development — it's different from your production webhook secret. **Test cards:** | Card number | Result | |---|---| | `4242 4242 4242 4242` | Payment succeeds | | `4000 0000 0000 0002` | Card declined | | `4000 0025 0000 3155` | Requires 3D Secure authentication | | `4000 0000 0000 9995` | Insufficient funds | Use any future expiry date, any CVC, any billing postcode. **Trigger specific events manually:** ```bash # Simulate a subscription renewal stripe trigger invoice.payment_succeeded # Simulate a failed payment stripe trigger invoice.payment_failed # Simulate a cancellation stripe trigger customer.subscription.deleted ```

## Production Checklist Before going live: - [ ] Switch all environment variables from test (`sk_test_`, `pk_test_`) to live (`sk_live_`, `pk_live_`) in Vercel - [ ] Create a production webhook endpoint in Stripe Dashboard → Developers → Webhooks pointing to your live URL - [ ] Copy the new production webhook secret to Vercel environment variables - [ ] Enable Smart Retries in Stripe Dashboard → Billing settings → Automatic collection - [ ] Configure the Customer Portal in Stripe Dashboard → Customer Portal - [ ] Set up a failed payment dunning sequence (email at Day 1, Day 3, Day 7 of `past_due`) - [ ] Confirm `userId` is in `metadata` for both the checkout session and subscription - [ ] Test a full subscription cycle in Stripe test mode before switching to live - [ ] Set up Stripe tax settings if required for your customers' regions - [ ] Enable Adaptive Pricing for automatic local currency display

## Common Mistakes **Storing prices in your database — don't.** Stripe is the source of truth for pricing. When you change a plan's price in Stripe, your database won't know. Sync status (active/canceled) and period end — not amounts. **Using `request.json()` instead of `request.text()` in the webhook handler.** The raw body is required for signature verification. `request.json()` parses it first, breaking verification. Always use `request.text()`. **Skipping `userId` in checkout metadata.** The `checkout.session.completed` webhook is your first chance to link a Stripe customer to your user. Without `userId` in metadata, you're doing email lookups that break with test accounts and edge cases. **Returning 200 when your handler throws an error.** If your webhook handler throws an error and you return 200, Stripe marks the event as delivered and never retries. Return 500 on errors so Stripe retries. Return 400 only for invalid payloads that should never be retried. **Running the webhook handler on Edge runtime.** Stripe's `constructEvent` requires Node.js crypto APIs. Set `export const runtime = "nodejs"` in your webhook route. **Not handling cancellations gracefully.** When a user cancels, their subscription status becomes `canceled` but `current_period_end` is still in the future. Give them access until that date. Don't cut access on cancellation. **Not handling `customer.subscription.updated`.** Plan changes, trial conversions, and reactivations all fire this event. It's the most important event to handle after `checkout.session.completed`.

## Wrap Up The checkout form is five lines of code. The production billing system is everything else — webhooks, lifecycle management, failed payment recovery, portal integration, and the edge cases that only appear when real users interact with real subscriptions. Get webhooks right first. Everything downstream — access control, emails, analytics — depends on your database accurately reflecting what Stripe knows about each customer's subscription status. If you're building a SaaS and want your project management, deployment tracking, and analytics in one workspace alongside your billing work, check out [AdeptDev](https://adeptdev.io). Free for 7 days.

## How do I add Stripe subscriptions to a Next.js app? Install three packages: `stripe` (server SDK), `@stripe/stripe-js` (client redirect), and `@stripe/react-stripe-js` (React bindings). Create a shared Stripe client in `lib/stripe.ts`. Use a Server Action to create a checkout session with `mode: "subscription"` — always include your user's ID in the session metadata. Set up a webhook handler at `/api/stripe/webhook` to handle `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, and `invoice.payment_failed`. The webhook handler is where you sync subscription status to your database. ## How do I handle Stripe webhooks in Next.js? Create a Route Handler at `app/api/stripe/webhook/route.ts`. Use `request.text()` — not `request.json()` — to get the raw body required for signature verification. Verify the signature with `stripe.webhooks.constructEvent(body, signature, secret)`. Set `export const runtime = "nodejs"` because `constructEvent` requires Node.js crypto. Return 200 on success, 400 for invalid payloads, and 500 for handler errors (so Stripe retries). Make your handlers idempotent — Stripe delivers events at least once and may deliver the same event twice. ## Why does Stripe webhook signature verification fail in Next.js? The most common cause is using `request.json()` instead of `request.text()`. Stripe verifies the HMAC signature against the raw request body bytes. Parsing the body as JSON changes the byte representation, causing verification to fail. Always read the raw body with `request.text()` before passing it to `stripe.webhooks.constructEvent`. The second common cause is using the wrong webhook secret — your local development secret (from `stripe listen`) is different from your production webhook secret. ## How do I check if a user has an active subscription in Next.js? Store subscription status in your database, synced via Stripe webhooks. Check `subscriptionStatus` server-side in Server Components, Server Actions, and API Routes. An active subscription is `status === "active"` or `status === "trialing"`. After cancellation, the status becomes `canceled` but access should remain until `current_period_end` — so also allow access when `status === "canceled"` and `periodEnd > now`. Never trust client-side state for access control — always check the database on protected server-side operations. ## How do I let users manage their Stripe subscription in Next.js? Use Stripe's Customer Portal instead of building subscription management UI yourself. Enable it in Stripe Dashboard → Customer Portal settings. Create a Server Action that calls `stripe.billingPortal.sessions.create()` with the user's `stripeCustomerId` and a return URL. Redirect the user to `portalSession.url`. The portal handles upgrades, downgrades, cancellations, payment method updates, and invoice history. When users make changes, Stripe sends webhook events that your handlers sync to your database automatically. ## How do I test Stripe subscriptions locally in Next.js? Install the Stripe CLI with `brew install stripe/stripe-cli/stripe`. Run `stripe login` then `stripe listen --forward-to localhost:3000/api/stripe/webhook`. The CLI outputs a webhook signing secret — use this as `STRIPE_WEBHOOK_SECRET` in `.env.local`. For test payments, use card `4242 4242 4242 4242` with any future expiry and any CVC. Trigger specific webhook events manually with `stripe trigger invoice.payment_succeeded` or `stripe trigger customer.subscription.deleted` to test your handlers without completing a full checkout. ## What Stripe events should I handle for subscriptions? The minimum set for a production subscription SaaS: `checkout.session.completed` (user subscribes — create customer record and grant access), `customer.subscription.updated` (plan change, trial conversion, reactivation), `customer.subscription.deleted` (cancellation confirmed — remove access after period end), `invoice.payment_succeeded` (renewal — trigger renewal email or analytics), and `invoice.payment_failed` (start dunning sequence — email user, update status to `past_due`). Handle `customer.subscription.trial_will_end` if you offer trials to send a reminder email before the trial converts.