Stripe Customer Portal integration in Next.js

The Customer Portal is Stripe’s hosted page for payment methods, invoices, and cancellation. You create a Billing Portal Session and redirect. The Stripe Subscription Starter does that in src/app/api/stripe/portal/route.ts. The Next.js SaaS Boilerplate does not include this route.

The handler

export async function GET() {
  const user = await currentUser();
  if (!user?.stripeCustomerId) {
    return NextResponse.redirect(new URL("/pricing", process.env.APP_URL));
  }
  const session = await stripe().billingPortal.sessions.create({
    customer: user.stripeCustomerId,
    return_url: `${process.env.APP_URL}/dashboard`
  });
  return NextResponse.redirect(session.url);
}

billingPortal.sessions.create needs an existing customer id. The Checkout route writes stripeCustomerId when it creates the customer, and the webhook writes it again from session.customer. If that column is null, the kit sends the user to /pricing instead of calling Stripe.

return_url is where Stripe sends the browser when they leave the portal. It is your dashboard, not a Stripe URL.

Dashboard configuration

In the Stripe Dashboard, open Billing, then Customer portal, and save a configuration. The first billingPortal.sessions.create call fails with a Stripe error if no portal configuration exists. The Node SDK 17 does not create that configuration for you.

Decide there whether customers may cancel, switch prices, or only update a card. The kit does not pass flow_data, so the portal uses the Dashboard defaults.

Cancellation still needs a webhook

The portal cancels the subscription inside Stripe. Your plan column changes only when customer.subscription.updated or customer.subscription.deleted hits the webhook. A portal link without that route leaves canceled users on pro until you refresh them by hand.

The portal does not replace Checkout. New subscribers still start at Stripe Checkout. The portal is for people who already have stripeCustomerId.

Want to skip the setup? The Stripe Subscription Starter already includes the portal route, Checkout, and the webhook that applies cancellations.