How to Build a Stripe Customer Portal in Next.js SaaS

When building a B2B SaaS application, one feature that often gets overlooked is the customer portal. It's tough when a lot of the complexity is hidden — Stripe handles the billing, but your users still need a place to manage their subscriptions, update payment methods, view invoices, and cancel or upgrade their plans.

That's where the Stripe Customer Portal comes in. In this guide, we'll walk through how to integrate it into a Next.js SaaS application step by step.

What is the Stripe Customer Portal?

The Stripe Customer Portal is a hosted UI that lets your customers manage their own billing. Instead of building a custom billing dashboard, you redirect your users to Stripe's portal where they can:

View and download invoices
Update their payment method
Cancel or upgrade their subscription
Manage billing details

The best part? You don't have to build any of this yourself.

Prerequisites

Before we start, make sure you have:

A Next.js application (v13+ with App Router recommended)
A Stripe account with billing enabled
Stripe's Node.js SDK installed: npm install stripe

Step 1: Enable the Customer Portal in Stripe Dashboard

First, go to your Stripe Dashboard → Settings → Billing → Customer Portal and enable it. Configure what customers can and cannot do (cancel subscriptions, update payment methods, etc.).

Step 2: Create a Customer Portal Session API Route

Create a new API route in your Next.js app:

// app/api/billing/portal/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
import { getServerSession } from 'next-auth';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: NextRequest) {
  const session = await getServerSession();

  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // Get the customer's Stripe customer ID from your database
  const user = await getUserFromDB(session.user.email);

  if (!user?.stripeCustomerId) {
    return NextResponse.json(
      { error: 'No billing account found' },
      { status: 400 }
    );
  }

  const portalSession = await stripe.billingPortal.sessions.create({
    customer: user.stripeCustomerId,
    return_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard/billing`,
  });

  return NextResponse.json({ url: portalSession.url });
}

Step 3: Add a "Manage Billing" Button to Your UI

Now create a client component that calls this API and redirects the user:

// components/BillingPortalButton.tsx
'use client';

import { useState } from 'react';

export function BillingPortalButton() {
  const [loading, setLoading] = useState(false);

  const handleManageBilling = async () => {
    setLoading(true);
    try {
      const res = await fetch('/api/billing/portal', { method: 'POST' });
      const data = await res.json();

      if (data.url) {
        window.location.href = data.url;
      }
    } catch (error) {
      console.error('Failed to open billing portal:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleManageBilling} disabled={loading}>
      {loading ? 'Loading...' : 'Manage Billing'}
    </button>
  );
}

Step 4: Handle the Return URL

When a customer finishes in the portal, Stripe redirects them back to your return_url. Make sure this page exists and ideally refreshes the user's subscription status.

// app/dashboard/billing/page.tsx
import { getSubscriptionStatus } from '@/lib/stripe';export default async function BillingPage() {
  const subscription = await getSubscriptionStatus();

  return (
    <div>
      <h1>Billing</h1>
      <p>Current plan: {subscription.plan}</p>
      <p>Status: {subscription.status}</p>
      <BillingPortalButton />
    </div>
  );
}

Step 5: Sync Subscription Changes via Webhooks

When a customer makes changes in the portal, Stripe fires webhooks. Make sure you're listening to:

customer.subscription.updated — plan change or cancellation scheduled
customer.subscription.deleted — subscription fully cancelled
invoice.payment_succeeded — successful renewal
invoice.payment_failed — failed payment

// app/api/webhooks/stripe/route.ts
export async function POST(req: NextRequest) {
  const body = await req.text();
  const sig = req.headers.get('stripe-signature')!;

  const event = stripe.webhooks.constructEvent(
    body,
    sig,
    process.env.STRIPE_WEBHOOK_SECRET!
  );

  switch (event.type) {
    case 'customer.subscription.updated':
      await syncSubscriptionToDatabase(event.data.object);
      break;
    case 'customer.subscription.deleted':
      await handleSubscriptionCancelled(event.data.object);
      break;
  }

  return NextResponse.json({ received: true });
}

Common Gotchas

1. Stripe customer ID not saved: When a user first subscribes, save their stripeCustomerId in your database immediately. Without it, you can't create portal sessions.

2. Multiple customers for the same email: Use stripe.customers.list({ email }) to check if a customer already exists before creating a new one.

3. Portal not configured: If you get a "Customer portal not enabled" error, make sure you've activated the portal in your Stripe Dashboard settings.

4. Webhook signature verification failing: Always use the raw request body (not parsed JSON) for webhook signature verification.

Wrapping Up

The Stripe Customer Portal is one of the fastest wins you can add to a SaaS product. In under an hour, you give your users full control over their billing without building a single billing UI component from scratch.

If you're starting a new SaaS project and want all of this — Stripe billing, customer portal, webhooks, and subscription management — already wired up and production-ready, check out Kostra, a Next.js SaaS boilerplate that includes complete Stripe integration out of the box.

Originally published on the Kostra blog — a production-ready Next.js SaaS boilerplate.

推荐订阅源

DEV Community