DEV Community: Prince

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

Prince — Mon, 25 May 2026 11:02:03 +0000

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.

How I built a SaaS in 48 hours

Prince — Mon, 04 May 2026 12:39:53 +0000

Last to last weekend i had an idea for a SaaS popped into my head. Pretty straightforward: a service that helps developers write better documentation, giving readability scores and improving the content.

Pretty basic concept. Clear problem. There is market demand.

Ordinarily, the first couple weeks would go into just setting things up. This time I took a different route. I leveraged the power of Kostra a production-ready Next.js SaaS boilerplate and had everything live within 48 hours.

Here's how that went down:

Hour 0: The turning point
All the SaaSes I've developed over the years followed the exact same pattern: excitement on day one, followed by weeks wasted handling Stripe, authentication, and initial configuration with no real product development happening.

With this project, I decided not to reinvent the wheel. For some time already I have been following Kostra a Next.js template with authentication, Stripe payments, file uploads, email capabilities, admin panel and even a blog all prebuilt and ready to use.

Hours 1-2: Initial Setup
Fork the project. Create environment variables. Connect Stripe and the database. Deploy on Vercel.

Completed.

In two hours, I achieved:

OAuth & password authentication
Stripe subscriptions setup
Admin dashboard live
Resend for email
Production URL

No need for debugging any authentication flow. No need to struggle with Stripe documentation.

Hours 3 to 8: Building the product
After taking care of the foundations, I started working on the actual product.

It required three main components:

Input text UI
Built using Kostra's atomic component library within less than an hour.
API endpoint for analyzing text
This was fairly easy due to Kostra’s repo/service architecture; one single-file service was sufficient.
Results UI
Scores, suggestions, and rephrased text. Again, this was built quickly using ready-made components.

In less than eight hours, I had the product up and running. Text input > analysis results – that's it!

Hours 9 to 16: Billing
Here's where many projects fail to deliver on time. Billing via Stripe might take days.

Given that Kostra has Stripe integration out-of-the-box, I only needed to:

Create two tiers of subscriptions: free plan (five uses per month) and pro plan ($19 monthly).
Use the credit system of Kostra for tracking usage.
Gate the API endpoint with usage limits.
Set up a pricing page with Stripe Checkout.

No need to configure the billing dashboard from scratch.

Total effort: six hours instead of several days.

Hours 17-24: Auth customizations, user setup, email
The auth part was done, so I just worked on:

Onboarding form: Added use case and team size field
Welcome email: Duplicated one of the templates and customized it (45 min)
Limits on usage: Automated through credits system

Nothing too strenuous here.

Hours 25-36: Polishing
This is when you get to do things that make it feel like an actual product:

Error states for API requests
Loading states
Empty state for new accounts
Mobile responsiveness (this is mostly done by now)
Landing page (very simple)

Used the in-built blog for the launch post.

Hours 37-48: Testing & Launch
Kostra has jests and CI/CD included. I tested the following:

Text processing
Subscription gates

Tested everything and all passed.

After that, did a soft launch into a few communities.

In those first 48 hours, I had:

Live SaaS on a real domain
3 subscribers ($19/mo)
17 free users
No infra problems

Here’s what 48 hours really looked like:

Hours 1-2: Initial Setup
Hours 3-8: Core Product Development
Hours 9-16: Billing Integration
Hours 17-24: User Onboarding + Email Integration
Hours 25-36: Finalization
Hours 37-48: Testing + Launch

What didn’t I have to build

OAuth/Authentication, one time password generation, JWT auth etc.
Stripe integration checkout, subscriptions
Billing portal
Credit/usage system
Admin portal
Email system
Files upload capability

Each of these tasks takes several days to complete. In total, this is many weeks of effort that I didn’t have to spend.
Trade-offs

Kostra has a cost $150 upfront.
It’s opinionated, too. You’re building on its patterns (services, components, architecture). This is usually helpful, but sometimes constraining.

If you want to build an entirely custom architecture, you may find this frustrating.
However, if you’re building the typical SaaS application (authentication, billing, users, email), it’s an excellent trade-off.
Would I use it again?
Absolutely.

I’ve probably saved three weeks at minimum. Even more importantly, it allowed me to focus on the real application and not worry about recreating infrastructure that I’ve built many times before.
If you’re trying to get something done quickly, rather than reinventing the wheel, Kostra makes sense.

Would I Use It Again?
Yes. Without hesitation.
The production-ready Next.js boilerplate saved me at minimum three weeks of setup work. At my hourly rate that is worth far more than $150. But more importantly, it kept me focused on the problem I was actually trying to solve instead of infrastructure I have solved before.
If you are building a SaaS product and want to skip straight to the product, Kostra is the nextjs saas starter I would recommend. It is the foundation I wish I had on every project I built before this one.
You can check out kostra at : https://kostra.io/

What I Learned Building a Production-Ready Next.js Boilerplate

Prince — Wed, 29 Apr 2026 11:26:37 +0000

I have been working on many SaaS products for some years now. In each of them, my workflow was pretty much the same during the first two to four weeks of development – setting up authentication, connecting Stripe, creating an admin dashboard, configuring emails before even thinking about the actual product.

This is when I realized the need for a production-ready Next.js boilerplate that covers all those boring tasks from the beginning.
Here is what I learned along the way.

Why Most Next.js Boilerplates Are Failing
Google "nextjs boilerplate" and you'll find a dozen different options. All of them will give you something like a good starting point with TypeScript and TailwindCSS. But that is it.
Sure, it's fine if you are trying something as a personal hobby project. It's not fine if you want to build a real SaaS product.
In my opinion, a proper production-ready Next.js boilerplate needs to tackle problems you haven't faced yet not just the ones you already know.
The True Cost of Creating a SaaS Product from Scratch
Before building Kostra, I tracked how much time I needed to do some common setups for each of my SaaS projects:
• Authentication using Google OAuth, email/password, and OTP verification: 3-4 days
• Stripe integration with subscriptions, one-time payments, webhooks, billing portal: 4-5 days
• A file upload system with S3, pre-signed URLs, and private buckets: 2-3 days
• Admin panel with user management and role permissions: 3-4 days
• Email system for sending templates with a flexible provider: 2-3 days
• Blog/CMS with categories, SEO slugs, and Rich Text Editor: 2-3 days
That is about four-five weeks worth of setups before even coding a single line of your product itself. On every new project.
Even if you value your time at $50/hour, that makes almost $10,000 in setups per project. Even reusing some code is not enough to reduce it.
What a True Next.js SaaS Boilerplate Should Have
In order to create a proper Next.js SaaS boilerplate, I wrote down all the necessary features I would expect from a production app.

1. Authentication System
A basic auth implementation is always easy. A production-ready auth system requires lots of work. Here are some features that Kostra comes with:
• Support for Google OAuth and email/password by default
• OTP verification for login without using passwords
• JWT-based sessions with secure cookies
• Password reset system with expiring tokens
• Role-based authentication (admin and user routes)

Most nextjs boilerplate options end their auth implementation after saying "users can sign in". And it isn't enough for a production app.

**2. Comprehensive Stripe Integration
Creating a checkout page for payments is easy. Integrating with Stripe in a SaaS app requires more. Here is what Kostra comes with for a Stripe integration:
• Subscription management (upgrades/downgrades)
• Payments and one-time payments
• Handling all important events via webhooks
• A billing portal where customers can manage their own subscriptions
• Credits system for usage-based payments
It takes the longest to create a Stripe integration correctly because Stripe offers a wide range of possible solutions and a lot of edge cases.

3. Real File Management System
Saving files locally in dev environment is okay. Storing them securely on a cloud service requires some extra steps. Kostra uses Cloudflare R2 and S3 and includes such important things as:
• Pre-signed URLs for secure direct uploads
• Public and private buckets for storing sensitive files
• A drag-and-drop interface for uploading files
• Organization of files based on their purposes

4. Proper Architecture
This is where many boilerplate saas apps cut off a lot of corners. In Kostra, there are such architectural solutions as:
• Atomic Design with UI components being atoms, molecules, and organisms for easier maintainability
• Repository and Service patterns to separate concerns and easily modify your code
• Factory Patterns to connect external services (email providers, cloud providers) without modifying your code
• Integration with Jest for running integration tests and CI/CD
Poor architecture seems cheap until you realize that your app has reached a point where it starts slowing you down and costing a lot of money for rewriting everything.

5. Other Features a SaaS Product Requires
In addition to the mentioned ones, a full-featured saas template needs:
• A blog/CMS with SEO-friendly slugs and Rich Text Editor
• Forms for capturing leads and contacting customers
• Sending email campaigns and templates for Resend and AWS SES
• Managing users with filtering, pagination, soft deletion, and onboarding status
• Admin panel with information about all registered users, credits, and subscribed plans

What I Would Do Differently
Think about architecture first. I built several features too early which I had to rewrite later because of poor architecture decisions. Thinking about repositories and services first could save me a week or two.
Don't underestimate emails. They seem like a minor feature but when you add templates, handling deliverability issues, using several providers for transactional and marketing messages, it becomes really complex.
Test your code from day one. Configuring Jest and setting up CI/CD from day one looks like an unnecessary overhead but skipping it until you see it as important slows everything down significantly.

Who This Is For
Kostra is for developers and product owners who want to launch a SaaS app fast without sacrificing its production-ready setup. For someone who wants to try out Next.js and have freedom in developing a personal project, T3 Stack or create-next-app may be a better option.
You can check it out here: https://kostra.io/