Mastering SaaS Subscriptions: Build a Scalable Platform with Next.js 15 & Stripe

Introduction & The Problem

The Solution Concept & Architecture

1. Frontend (Next.js 15 Client Components): User interacts with subscription options (e.g., 'Upgrade to Pro'). This triggers an API call to your Next.js backend.
2. Backend (Next.js 15 API Routes / Server Components): Your API routes handle creating Stripe Checkout sessions, managing customer portals, and securely interacting with the Stripe API using your secret key. This is where the heavy lifting of Stripe API calls happens.
3. Stripe Checkout / Customer Portal: Users are redirected to Stripe's hosted pages for payment entry, ensuring security and compliance. After successful payment, Stripe redirects the user back to your application.
4. Stripe Webhooks: Stripe asynchronously sends events (e.g., checkout.session.completed, customer.subscription.updated, invoice.payment_succeeded) to a dedicated webhook endpoint on your Next.js backend. This is crucial for updating your database.
5. Database: Stores user-specific subscription data (e.g., userId, stripeCustomerId, stripeSubscriptionId, planId, status, currentPeriodEnd). This data is updated primarily via webhook events, ensuring consistency.

Step-by-Step Implementation

1. Setup & Prerequisites

npx create-next-app@latest my-saas-app --typescript --eslint --app
cd my-saas-app

npm install stripe @prisma/client
npm install -D prisma

// prisma/schema.prisma
model User {
  id              String      @id @default(uuid())
  email           String      @unique
  stripeCustomerId String? @unique @map("stripe_customer_id")
  subscriptions   Subscription[]
}

model Subscription {
  id                 String     @id @default(uuid())
  userId             String     @map("user_id")
  user               User       @relation(fields: [userId], references: [id])
  stripeSubscriptionId String   @unique @map("stripe_subscription_id")
  stripeProductId    String   @map("stripe_product_id")
  stripePriceId      String   @map("stripe_price_id")
  status             String     // e.g., 'active', 'canceled', 'trialing'
  currentPeriodEnd   DateTime   @map("current_period_end")
  createdAt          DateTime   @default(now())
  updatedAt          DateTime   @updatedAt

  @@unique([userId, stripeProductId])
}

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_APP_URL=http://localhost:3000 // Your application's base URL

// lib/stripe.ts
import Stripe from 'stripe';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-06-20',
});

2. Create a Stripe Checkout Session (Next.js API Route)

// app/api/create-checkout-session/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export async function POST(req: NextRequest) {
  try {
    // In a real app, you'd get the userId from an authenticated session
    // For this example, let's assume a hardcoded userId or get it from request body
    const { priceId, userId } = await req.json(); // priceId e.g., 'price_123'

    if (!userId) {
      return new NextResponse('User ID is required', { status: 400 });
    }

    let customerId;
    // Find or create a Stripe customer for the user
    let user = await prisma.user.findUnique({ where: { id: userId } });

    if (!user) {
      // This should ideally be handled during user registration/login
      // For demo, creating a dummy user if not found
      user = await prisma.user.create({
        data: { id: userId, email: `user-${userId}@example.com` }
      });
    }

    if (user.stripeCustomerId) {
      customerId = user.stripeCustomerId;
    } else {
      // Create a new Stripe customer
      const customer = await stripe.customers.create({
        email: user.email,
        metadata: { userId: user.id },
      });
      customerId = customer.id;
      await prisma.user.update({
        where: { id: userId },
        data: { stripeCustomerId: customerId },
      });
    }

    const checkoutSession = await stripe.checkout.sessions.create({
      customer: customerId,
      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}/dashboard?canceled=true`,
      subscription_data: {
        metadata: { userId: user.id, priceId: priceId },
      },
      allow_promotion_codes: true,
    });

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

  } catch (error) {
    console.error('Error creating checkout session:', error);
    return new NextResponse('Internal Server Error', { status: 500 });
  }
}

3. Handle Stripe Webhooks (Next.js API Route)

// app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';
import { PrismaClient } from '@prisma/client';
import Stripe from 'stripe';

const prisma = new PrismaClient();

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get('stripe-signature') as string;

  let event: Stripe.Event;

  try {
    // Verify the webhook signature to ensure the event is from Stripe
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET! // Your webhook secret from Stripe Dashboard
    );
  } catch (error: any) {
    console.error(`Webhook signature verification failed: ${error.message}`);
    return new NextResponse(`Webhook Error: ${error.message}`, { status: 400 });
  }

  // Handle the event
  switch (event.type) {
    case 'checkout.session.completed':
      const checkoutSession = event.data.object as Stripe.Checkout.Session;
      const subscriptionId = checkoutSession.subscription as string;
      const customerId = checkoutSession.customer as string;

      if (subscriptionId && customerId) {
        const subscription = await stripe.subscriptions.retrieve(subscriptionId);
        const userId = checkoutSession.metadata?.userId; // Retrieved from session metadata
        const priceId = checkoutSession.metadata?.priceId; // Retrieved from session metadata

        if (userId && priceId) {
          await prisma.subscription.upsert({
            where: { stripeSubscriptionId: subscription.id },
            update: {
              status: subscription.status,
              currentPeriodEnd: new Date(subscription.current_period_end * 1000),
            },
            create: {
              userId: userId,
              stripeCustomerId: customerId,
              stripeSubscriptionId: subscription.id,
              stripeProductId: subscription.items.data[0].price.product as string,
              stripePriceId: priceId,
              status: subscription.status,
              currentPeriodEnd: new Date(subscription.current_period_end * 1000),
            },
          });
          // Optionally, update the user's stripeCustomerId if it was just created
          await prisma.user.update({
            where: { id: userId },
            data: { stripeCustomerId: customerId },
          });
        }
      }
      break;
    case 'customer.subscription.updated':
    case 'customer.subscription.deleted':
      const subscription = event.data.object as Stripe.Subscription;
      // Retrieve the associated user from your database using stripeCustomerId
      const userWithSubscription = await prisma.user.findFirst({ where: { stripeCustomerId: subscription.customer as string } });

      if (userWithSubscription) {
        await prisma.subscription.update({
          where: { stripeSubscriptionId: subscription.id },
          data: {
            status: subscription.status,
            currentPeriodEnd: new Date(subscription.current_period_end * 1000),
          },
        });
      }
      break;
    case 'invoice.payment_succeeded':
      // Handle successful invoice payments (e.g., send confirmation email)
      const invoice = event.data.object as Stripe.Invoice;
      // console.log('Invoice payment succeeded for:', invoice.customer_email);
      break;
    // ... handle other event types as needed
    default:
      console.warn(`Unhandled event type ${event.type}`);
  }

  return new NextResponse('OK', { status: 200 });
}

4. Frontend Integration (Client Component)

// app/dashboard/page.tsx (or any client component)
'use client';

import { useState } from 'react';
import { useRouter } from 'next/navigation';

export default function DashboardPage() {
  const router = useRouter();
  const [loading, setLoading] = useState(false);
  const userId = 'clxxd8e39000008jp2k3a7a9u'; // Replace with actual authenticated user ID

  const handleSubscribe = async (priceId: string) => {
    setLoading(true);
    try {
      const response = await fetch('/api/create-checkout-session', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ priceId, userId }),
      });

      const { url } = await response.json();
      if (url) {
        router.push(url); // Redirect to Stripe Checkout
      } else {
        alert('Failed to create checkout session.');
      }
    } catch (error) {
      console.error('Subscription error:', error);
      alert('An error occurred during subscription.');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="container mx-auto p-4">
      <h1 className="text-3xl font-bold mb-6">Your Dashboard</h1>
      <p className="mb-4">Current Plan: Free</p>
      <button
        onClick={() => handleSubscribe('price_1PPjXqJqfH0B2g3i4a5c6d7e')}
        disabled={loading}
        className="bg-blue-600 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded disabled:opacity-50"
      >
        {loading ? 'Redirecting...' : 'Upgrade to Pro'}
      </button>
    </div>
  );
}

Optimization & Best Practices

1. Security First: Always verify Stripe webhook signatures. Never expose your STRIPE_SECRET_KEY client-side. Use environment variables securely. Implement rate limiting on your webhook endpoint to prevent abuse.
2. Idempotency for Webhooks: Stripe webhooks can occasionally send duplicate events. Implement idempotency keys or a mechanism to check if an event has already been processed to prevent issues like double-charging or incorrect state updates. Our upsert logic in Prisma helps, but you might need more granular control for complex workflows.
3. Error Handling & Logging: Implement robust try-catch blocks and detailed logging. When a webhook fails, Stripe will retry. Ensure your logging helps you diagnose issues quickly.
4. Database Transactions: For complex webhook logic involving multiple database updates, wrap them in a database transaction to ensure atomicity. If any part fails, the entire transaction can be rolled back.
5. Stripe CLI for Local Testing: Use the Stripe CLI (stripe listen --forward-to localhost:3000/api/webhooks/stripe) to forward webhook events to your local development server. This is indispensable for testing.
6. User Experience: Provide clear feedback to users about their subscription status. Implement a 'billing portal' where users can manage their subscriptions directly via Stripe's hosted portal (stripe.billingPortal.sessions.create).
7. Scalability: Next.js API routes are serverless functions, scaling automatically with demand. Database indexing on userId, stripeCustomerId, and stripeSubscriptionId will ensure fast lookups as your user base grows.

Business Impact & ROI

• Accelerated Time-to-Market: Leverage Stripe's battle-tested infrastructure to launch subscription features in days, not months. This allows your business to start generating recurring revenue much faster, freeing up development cycles for core product innovation.
• Reduced Operational Overhead & Cost Savings: Stripe automates complex tasks like invoicing, tax calculation, dunning management (recovering failed payments), and compliance. This significantly reduces manual administrative work, saving hundreds of developer and finance hours per month, and directly impacts your bottom line by reducing operational costs and increasing payment recovery rates.
• Enhanced Security & Compliance: Offload the burden of PCI DSS compliance and sensitive data handling to Stripe. This minimizes your risk of data breaches and avoids the substantial investment required to build and maintain secure payment infrastructure in-house, protecting your brand reputation.
• Improved User Experience & Conversion: Stripe's optimized checkout flows and customer portals lead to higher conversion rates for new subscribers and reduced churn for existing ones. Flexible pricing models, promotions, and easy self-service options contribute to customer satisfaction and loyalty.
• Global Reach & Scalability: Stripe supports a multitude of currencies and payment methods globally, allowing your SaaS to expand into new markets effortlessly. The serverless nature of Next.js API routes ensures your billing system scales seamlessly with your user growth without requiring costly infrastructure overhauls.

Conclusion