The answer is multi-tenancy: an architecture where one application dynamically serves isolated experiences to many different users, often through subdomains.

In this tutorial, you'll build a multi-tenant portfolio SaaS platform from scratch using Next.js, Express, and Prisma. Each user who signs up gets their own portfolio site, served on their own subdomain — generated instantly, powered by a single backend, and stored in a single database.

Here's what you'll build:

• A landing page where users fill out a form to create their portfolio

• An Express + Prisma backend that stores each user as a "tenant"

• A Next.js middleware layer that detects subdomains and routes requests dynamically

• A JSON-driven template system that controls which sections appear on each portfolio

• A production-ready portfolio page served at name.localhost:3000 in development and name.yourdomain.com in production

You can find the complete source code in the GitHub repositories linked at the end of this tutorial.

Table of Contents

• Prerequisites

• What is Multi-Tenancy?

• How to Set Up the Backend

  • How to Install Dependencies

  • How to Configure TypeScript for ESM

  • How to Initialize Prisma

• How to Define the Prisma Schema

• How to Run Your First Migration

• How to Generate and Instantiate the Prisma Client

  • How to Generate the Client

  • How to Instantiate the Client

• How to Seed a Template

• How to Build the Express API

  • How to Install Express

  • How to Create the Server Entry Point

  • How to Create the Express App

  • How to Create the Tenant Controller

  • How to Create the Tenant Routes

  • How to Start the Server

• How to Create the Next.js Frontend

• How to Add Subdomain Routing with Middleware

• How to Build the Landing Page

  • How to Update the Layout

  • How to Create the Home Page

• How to Build the Tenant Portfolio Page

• How to Test the Full Flow

• Next Steps

• Conclusion

• Source Code

Prerequisites

Before you begin, make sure you have the following:

• Node.js (version 18 or higher) installed on your machine

• A basic understanding of React, TypeScript, and REST APIs

• Familiarity with Prisma ORM (you don't need to be an expert)

• A code editor like VS Code

You'll use Prisma Postgres as your database, so you won't need to set up a separate database server locally. Prisma handles the connection string and adapter configuration for you.

What is Multi-Tenancy?

Multi-tenancy is an architectural pattern where a single application serves multiple users — called tenants — each with isolated data and often their own URL.

Here's how the flow works in this tutorial:

1. A user visits your landing page and fills out a form with their name, bio, and skills.

2. Your Express backend creates a new tenant record in the database and generates a slug from their name.

3. The browser redirects the user to their-name.localhost:3000.

4. Your Next.js middleware detects the subdomain, extracts the slug, and rewrites the request to /tenant/their-name internally.

5. The tenant page fetches that user's data from the API and renders their portfolio.

The key insight is that the URL in the browser never changes — the rewrite is invisible to the user. One Next.js app serves every tenant dynamically.

How to Set Up the Backend

Start by creating a project folder with separate directories for the backend and frontend:

mkdir portfolio-saas && cd portfolio-saas
mkdir portfolio-api portfolio-client

Navigate into the backend directory and initialize a new Node.js project:

cd portfolio-api
npm init -y

How to Install Dependencies

Install TypeScript, Prisma, and the supporting packages:

npm install typescript tsx @types/node --save-dev
npx tsc --init
npm install prisma @types/node @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg dotenv

How to Configure TypeScript for ESM

Open tsconfig.json and replace its contents with:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true,
    "ignoreDeprecations": "6.0",
    "types": ["node"]
  }
}

Then open package.json and add "type": "module" to enable ESM:

{
  "type": "module"
}

How to Initialize Prisma

Run the following command to initialize Prisma and generate your schema setup:

npx prisma init --db --output ../generated/prisma

This command creates a prisma/schema.prisma file, a .env file with your database connection string, and a generated Prisma configuration folder.

How to Define the Prisma Schema

Open prisma/schema.prisma and replace its contents with the following:

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model Tenant {
  id         String   @id @default(uuid())
  slug       String   @unique
  name       String
  bio        String
  skills     String[]
  templateId String
  createdAt  DateTime @default(now())
}

model Template {
  id     String @id @default(uuid())
  name   String
  config Json
}

model Post {
  id         String   @id @default(uuid())
  title      String
  content    String
  tenantSlug String
  createdAt  DateTime @default(now())
}

Let's look at what each model does.

The Tenant model represents a user who has signed up and created a portfolio. The slug field is generated from their name (for example, "John Doe" becomes john-doe) and is used as their subdomain. The templateId links each tenant to a template that controls their portfolio's layout.

The Template model stores layout configuration as JSON. Instead of hardcoding sections like "hero" or "skills" into your components, you store them in the database. This means you can add or remove sections for different templates without touching any component code.

The Post model is included for future extensibility — you can use it to let tenants publish blog posts on their portfolio.

How to Run Your First Migration

Run the following command to create your database tables based on the schema:

npx prisma migrate dev --name init

This command creates the database tables, generates a migration file, and applies the migration to your database. After it runs, your Postgres database structure matches your Prisma schema exactly.

How to Generate and Instantiate the Prisma Client

How to Generate the Client

Run this command to generate a fully type-safe Prisma Client based on your schema:

npx prisma generate

You only need to run this once after each schema change. The generated client lives in the ../generated/prisma folder you configured earlier.

How to Instantiate the Client

Create a new file at lib/prisma.ts and add the following:

import 'dotenv/config';
import { PrismaPg } from '@prisma/adapter-pg';
import { PrismaClient } from '../generated/prisma/client';

const connectionString = process.env.DATABASE_URL as string;

const adapter = new PrismaPg({ connectionString });
const prisma = new PrismaClient({ adapter });

export default prisma;

This file creates a single shared Prisma Client instance that your entire backend will import. The PrismaPg adapter connects Prisma to your Postgres database using the connection string from your .env file.

How to Seed a Template

Your platform needs at least one template in the database before any tenant can sign up. Instead of hardcoding layout decisions into your components, you'll store the template configuration as JSON and read it at runtime.

Create a new file at prisma/seed.ts and add the following:

import prisma from '../lib/prisma';

async function main() {
  await prisma.template.create({
    data: {
      name: 'minimal',
      config: {
        theme: {
          primaryColor: '#6366f1',
          background: 'dark',
        },
        sections: {
          hero: true,
          about: true,
          skills: true,
          projects: true,
          blog: true,
          contact: true,
        },
      },
    },
  });

  console.log('Template seeded successfully.');
}

main()
  .catch((e) => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

The config field is stored as JSON in Postgres. When a tenant's portfolio loads, your frontend reads this JSON to decide which sections to show. Setting hero: false on a template would hide the hero section for every tenant using that template — no code changes needed.

Now add a seed script to your package.json:

{
  "scripts": {
    "seed": "tsx prisma/seed.ts"
  }
}

Run it:

npm run seed

Your database now has a default template ready to attach to new tenants.

How to Build the Express API

Now you'll build the backend API that creates tenants and retrieves their data.

How to Install Express

npm install express cors
npm install -D @types/express @types/cors

How to Create the Server Entry Point

Create src/index.ts:

import app from './app';

const PORT = 8080;

app.listen(PORT, () => {
  console.log('Server is running on port 8080');
});

How to Create the Express App

Create src/app.ts:

import express from 'express';
import cors from 'cors';
import tenantRoutes from './routes/tenant.routes';

const app = express();

app.use(cors());
app.use(express.json());
app.use('/api', tenantRoutes);

export default app;

This file sets up CORS so your Next.js frontend can communicate with the API, parses JSON request bodies, and mounts all tenant routes under the /api prefix.

How to Create the Tenant Controller

Create src/controllers/tenant.controller.ts:

import { Request, Response } from 'express';
import prisma from '../../lib/prisma';

export async function createTenant(req: Request, res: Response) {
  const { name, bio, skills } = req.body;

  if (!name || !bio || !skills) {
    return res.status(400).json({ error: 'Missing required fields' });
  }

  const slug = name.toLowerCase().replace(/\s+/g, '-');

  const template = await prisma.template.findFirst();
  if (!template) {
    return res.status(500).json({ error: 'No template found' });
  }

  const tenant = await prisma.tenant.create({
    data: {
      slug,
      name,
      bio,
      skills,
      templateId: template.id,
    },
  });

  res.json({ slug: tenant.slug });
}

export async function getTenant(req: Request, res: Response) {
  const slug = req.params.slug;

  if (!slug || typeof slug !== 'string') {
    return res.status(400).json({ error: 'Invalid slug parameter' });
  }

  const tenant = await prisma.tenant.findUnique({
    where: { slug },
  });

  if (!tenant) {
    return res.status(404).json({ error: 'Tenant not found' });
  }

  const template = await prisma.template.findUnique({
    where: { id: tenant.templateId },
  });

  res.json({ tenant, template });
}

Let's break down what this controller does.

createTenant takes the user's name, bio, and skills from the request body. It generates a slug by lowercasing the name and replacing spaces with hyphens — so "Jane Smith" becomes jane-smith. It then finds the first available template and creates the tenant record in the database, linking the template to the new tenant via templateId.

getTenant looks up a tenant by their slug and also fetches the template attached to them. Both pieces of data are returned together so the frontend can render the portfolio and apply the correct layout configuration in a single API call.

How to Create the Tenant Routes

Create src/routes/tenant.routes.ts:

import { Router } from 'express';
import { createTenant, getTenant } from '../controllers/tenant.controller';

const router = Router();

router.post('/tenants', createTenant);
router.get('/tenants/:slug', getTenant);

export default router;

Your API now exposes two endpoints:

POST   /api/tenants        — creates a new tenant
GET    /api/tenants/:slug  — retrieves a tenant and their template

How to Start the Server

Add the dev script to your package.json:

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "seed": "tsx prisma/seed.ts"
  }
}

Run it:

npm run dev

You should see Server is running on port 8080 in your terminal. Your backend is ready.

How to Create the Next.js Frontend

Navigate to the portfolio-client directory and create a new Next.js project. Make sure to select Yes when the installer asks if you want to use Tailwind CSS:

cd ../portfolio-client
npx create-next-app@latest . --typescript --app --tailwind --eslint
npm install

Since create-next-app sets up Tailwind for you automatically, no extra configuration is needed. The tailwind.config.ts and the @tailwind directives in globals.css are already in place.

How to Add Subdomain Routing with Middleware

This is the heart of the multi-tenant architecture. You need a piece of code that runs before every request, reads the subdomain from the URL, and rewrites the request to the correct internal route — all without the user ever seeing the URL change.

Create a file called proxy.ts in the root directory:

import { NextRequest, NextResponse } from 'next/server';

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const host = request.headers.get('host') ?? '';

  const hostname = host.split(':')[0];
  const parts = hostname.split('.');

  // Local development: john.localhost:3000
  if (hostname.endsWith('localhost')) {
    const subdomain = parts[0];

    // Root localhost — load the landing page normally
    if (subdomain === 'localhost') {
      return NextResponse.next();
    }

    // Already rewritten — don't rewrite again
    if (pathname.startsWith('/tenant')) {
      return NextResponse.next();
    }

    return NextResponse.rewrite(new URL(`/tenant/${subdomain}`, request.url));
  }

  // Production: john.yourdomain.com
  if (parts.length > 2) {
    const subdomain = parts[0];

    if (subdomain !== 'www') {
      if (pathname.startsWith('/tenant')) {
        return NextResponse.next();
      }

      return NextResponse.rewrite(new URL(`/tenant/${subdomain}`, request.url));
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)',
  ],
};

Here's exactly what this proxy does, step by step.

It reads the host header from every incoming request and splits it on . to extract the subdomain. For a request to john.localhost:3000, the subdomain is john. For a request directly to localhost:3000, the subdomain is localhost itself — in which case the proxy lets the request through unchanged so the landing page loads normally.

When a subdomain is detected, the proxy rewrites the request URL from / to /tenant/john internally. This rewrite is invisible to the browser — the user still sees john.localhost:3000 in their address bar, but Next.js routes the request to your /tenant/[slug] page.

The if (pathname.startsWith('/tenant')) guard prevents infinite rewrite loops. Without it, the already-rewritten request would be rewritten again on the next pass through the middleware.

How to Build the Landing Page

How to Update the Layout

Open app/layout.tsx and update it:

import type { Metadata } from 'next';
import { Geist, Geist_Mono } from 'next/font/google';
import './globals.css';

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
});

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
});

export const metadata: Metadata = {
  title: 'Portfolio SaaS App',
  description: 'Create and host your portfolio with subdomains',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={`\({geistSans.variable} \){geistMono.variable} antialiased`}>
        {children}
      </body>
    </html>
  );
}

How to Create the Home Page

Create app/page.tsx:

'use client';

import { useState } from 'react';

export default function Home() {
  const [name, setName] = useState('');
  const [bio, setBio] = useState('');
  const [skills, setSkills] = useState('');

  const handleSubmit = async () => {
    const res = await fetch('http://localhost:8080/api/tenants', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        name,
        bio,
        skills: skills.split(',').map((s) => s.trim()),
      }),
    });

    const data = await res.json();
    window.location.href = `http://${data.slug}.localhost:3000`;
  };

  return (
    <div className="min-h-screen bg-gradient-to-br from-slate-900 to-slate-800 text-white flex flex-col">
      {/* Header */}
      <header className="flex items-center justify-between px-10 py-5">
        <span className="text-xl font-semibold tracking-wide">PortfolioSaaS</span>
        <nav className="flex gap-6 text-sm text-slate-400">
          <a href="#features" className="hover:text-white transition-colors">Features</a>
          <a href="#pricing" className="hover:text-white transition-colors">Pricing</a>
          <a href="#docs" className="hover:text-white transition-colors">Docs</a>
        </nav>
      </header>

      {/* Main */}
      <main className="flex flex-1 items-center justify-center px-6 py-10">
        <div className="w-full max-w-md bg-slate-800 rounded-2xl p-10 shadow-2xl">
          <h1 className="text-3xl font-bold mb-3">Create Your Portfolio</h1>
          <p className="text-slate-400 text-sm mb-8">
            Launch your personal portfolio instantly with your own subdomain.
          </p>

          <input
            type="text"
            placeholder="Your Name"
            onChange={(e) => setName(e.target.value)}
            className="w-full bg-slate-900 border border-slate-700 rounded-lg px-4 py-3 text-sm text-white placeholder-slate-500 focus:outline-none focus:border-indigo-500 mb-4"
          />

          <textarea
            placeholder="Short Bio"
            rows={4}
            onChange={(e) => setBio(e.target.value)}
            className="w-full bg-slate-900 border border-slate-700 rounded-lg px-4 py-3 text-sm text-white placeholder-slate-500 focus:outline-none focus:border-indigo-500 mb-4 resize-none"
          />

          <input
            type="text"
            placeholder="Skills (comma separated)"
            onChange={(e) => setSkills(e.target.value)}
            className="w-full bg-slate-900 border border-slate-700 rounded-lg px-4 py-3 text-sm text-white placeholder-slate-500 focus:outline-none focus:border-indigo-500 mb-6"
          />

          <button
            onClick={handleSubmit}
            className="w-full bg-indigo-600 hover:bg-indigo-500 text-white font-semibold py-3 rounded-lg transition-colors"
          >
            Create Portfolio
          </button>
        </div>
      </main>

      {/* Footer */}
      <footer className="text-center text-xs text-slate-500 py-5 border-t border-slate-800">
        © {new Date().getFullYear()} PortfolioSaaS. All rights reserved.
      </footer>
    </div>
  );
}

When a user submits the form, three things happen in sequence. First, a POST request creates a new tenant in your database. Second, the API returns the generated slug. Third, the browser redirects the user to their subdomain — their-name.localhost:3000 — where the middleware takes over and renders their portfolio.

How to Build the Tenant Portfolio Page

Create app/tenant/[slug]/page.tsx:

import type { Metadata } from 'next';

async function getTenant(slug: string) {
  const res = await fetch(`http://localhost:8080/api/tenants/${slug}`, {
    cache: 'no-store',
  });
  return res.json();
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  const { tenant } = await getTenant(slug);

  if (!tenant) {
    return {
      title: 'Portfolio Not Found',
      description: 'This portfolio does not exist.',
      robots: { index: false, follow: false },
    };
  }

  return {
    title: tenant.name,
    description:
      tenant.bio?.slice(0, 160) ||
      `Explore ${tenant.name}'s professional portfolio.`,
    openGraph: {
      title: tenant.name,
      description: tenant.bio,
      type: 'website',
    },
  };
}

function initials(name: string) {
  return name
    .split(' ')
    .filter(Boolean)
    .slice(0, 2)
    .map((n) => n[0]?.toUpperCase())
    .join('');
}

export default async function TenantPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const data = await getTenant(slug);

  const tenant = data?.tenant;
  const template = data?.template;

  if (!tenant) {
    return (
      <div className="min-h-screen bg-slate-900 text-white flex items-center justify-center">
        <h1 className="text-2xl font-bold text-slate-400">Portfolio not found</h1>
      </div>
    );
  }

  const primary = template?.config?.theme?.primaryColor || '#6366f1';

  // Template-driven section toggles with safe defaults
  const sections = {
    hero: true,
    about: true,
    skills: true,
    projects: true,
    blog: true,
    contact: true,
    ...(template?.config?.sections ?? {}),
  };

  const avatarUrl = tenant.avatarUrl as string | undefined;

  return (
    <div className="min-h-screen bg-gradient-to-br from-slate-900 via-slate-800 to-slate-900 text-slate-100">

      {/* Header */}
      <header className="sticky top-0 z-20 backdrop-blur-md bg-slate-900/60 border-b border-white/5">
        <div className="max-w-5xl mx-auto px-5 py-4 flex items-center justify-between gap-4">
          <div className="flex items-center gap-3 min-w-0">
            <span
              className="w-2.5 h-2.5 rounded-full shrink-0"
              style={{ backgroundColor: primary }}
            />
            <span className="font-semibold truncate">{tenant.name}</span>
          </div>

          <nav className="hidden md:flex items-center gap-5 text-sm text-slate-400">
            {(sections.hero || sections.about) && (
              <a href="#about" className="hover:text-white transition-colors">About</a>
            )}
            {sections.skills && (
              <a href="#skills" className="hover:text-white transition-colors">Skills</a>
            )}
            {sections.projects && (
              <a href="#projects" className="hover:text-white transition-colors">Projects</a>
            )}
            {sections.blog && (
              <a href="#blog" className="hover:text-white transition-colors">Blog</a>
            )}
            {sections.contact && (
              <a href="#contact" className="hover:text-white transition-colors">Contact</a>
            )}
          </nav>

          {sections.contact && (
            <a
              href="#contact"
              className="text-sm font-semibold px-4 py-2 rounded-full transition-transform hover:-translate-y-px"
              style={{ backgroundColor: primary, color: '#0b1020' }}
            >
              Hire me
            </a>
          )}
        </div>
      </header>

      {/* Hero / About */}
      {(sections.hero || sections.about) && (
        <section className="px-5 pt-20 pb-14" id="about">
          <div className="max-w-5xl mx-auto bg-white/[0.04] border border-white/[0.08] rounded-2xl p-7 shadow-2xl grid grid-cols-[110px_1fr] gap-6 items-center">

            {/* Avatar */}
            <div className="w-[110px] h-[110px] rounded-full overflow-hidden border border-white/10 bg-white/5 flex items-center justify-center shrink-0">
              {avatarUrl ? (
                // eslint-disable-next-line @next/next/no-img-element
                <img src={avatarUrl} alt={`${tenant.name} avatar`} className="w-full h-full object-cover" />
              ) : (
                <span className="text-2xl font-extrabold text-slate-200 tracking-tight">
                  {initials(tenant.name)}
                </span>
              )}
            </div>

            {/* Text */}
            <div className="min-w-0">
              <h1
                className="text-5xl font-extrabold tracking-tight leading-tight mb-3"
                style={{ color: primary }}
              >
                {tenant.name}
              </h1>
              <p className="text-slate-400 text-base leading-relaxed max-w-2xl">
                {tenant.bio}
              </p>
              <div className="flex flex-wrap gap-3 mt-5">
                {sections.contact && (
                  <a
                    href="#contact"
                    className="inline-flex items-center px-5 py-2.5 rounded-full text-sm font-semibold transition-transform hover:-translate-y-px"
                    style={{ backgroundColor: primary, color: '#0b1020' }}
                  >
                    Let&apos;s connect
                  </a>
                )}
                {sections.skills && (
                  <a
                    href="#skills"
                    className="inline-flex items-center px-5 py-2.5 rounded-full text-sm font-semibold text-slate-200 border border-white/10 bg-white/5 hover:border-white/20 transition-all hover:-translate-y-px"
                  >
                    View skills
                  </a>
                )}
              </div>
            </div>
          </div>
        </section>
      )}

      {/* Skills */}
      {sections.skills && (
        <section className="px-5 py-14 max-w-5xl mx-auto" id="skills">
          <h2 className="text-2xl font-bold text-center tracking-tight mb-7">Skills</h2>
          <div className="flex flex-wrap gap-3 justify-center">
            {tenant.skills.map((skill: string) => (
              <span
                key={skill}
                className="px-4 py-2 rounded-full text-sm font-semibold bg-white/5 backdrop-blur-sm hover:-translate-y-0.5 hover:shadow-lg transition-all"
                style={{ border: `1px solid ${primary}` }}
              >
                {skill}
              </span>
            ))}
          </div>
        </section>
      )}

      {/* Projects */}
      {sections.projects && (
        <section className="px-5 py-14 max-w-5xl mx-auto" id="projects">
          <h2 className="text-2xl font-bold text-center tracking-tight mb-7">Projects</h2>
          <div className="flex flex-wrap gap-3 justify-center">
            {['Portfolio SaaS', 'Multi-tenant Routing', 'Template Builder'].map((p) => (
              <span
                key={p}
                className="px-4 py-2 rounded-full text-sm font-semibold bg-white/5 backdrop-blur-sm hover:-translate-y-0.5 hover:shadow-lg transition-all"
                style={{ border: `1px solid ${primary}` }}
              >
                {p}
              </span>
            ))}
          </div>
        </section>
      )}

      {/* Blog */}
      {sections.blog && (
        <section className="px-5 py-14 max-w-5xl mx-auto" id="blog">
          <h2 className="text-2xl font-bold text-center tracking-tight mb-7">Blog</h2>
          <div className="flex flex-wrap gap-3 justify-center">
            {[
              'How I built this portfolio',
              'Next.js Middleware Tips',
              'Designing Templates',
            ].map((post) => (
              <span
                key={post}
                className="px-4 py-2 rounded-full text-sm font-semibold bg-white/5 backdrop-blur-sm hover:-translate-y-0.5 hover:shadow-lg transition-all"
                style={{ border: `1px solid ${primary}` }}
              >
                {post}
              </span>
            ))}
          </div>
        </section>
      )}

      {/* Contact */}
      {sections.contact && (
        <section className="px-5 pt-2 pb-16" id="contact">
          <div className="max-w-3xl mx-auto bg-white/[0.04] border border-white/[0.08] rounded-2xl p-7">
            <h2 className="text-xl font-bold mb-2">Contact</h2>
            <p className="text-slate-400 leading-relaxed mb-5">
              Want to work together? Send a message and I&apos;ll reply quickly.
            </p>
            <div className="flex flex-wrap gap-3">
              <a
                href={`mailto:hello@${tenant.slug}.com`}
                className="inline-flex items-center px-5 py-2.5 rounded-full text-sm font-semibold transition-transform hover:-translate-y-px"
                style={{ backgroundColor: primary, color: '#0b1020' }}
              >
                Email me
              </a>
              <a
                href="#about"
                className="inline-flex items-center px-5 py-2.5 rounded-full text-sm font-semibold text-slate-200 border border-white/10 bg-white/5 hover:border-white/20 transition-all hover:-translate-y-px"
              >
                Back to top
              </a>
            </div>
          </div>
        </section>
      )}

      {/* Footer */}
      <footer className="text-center text-xs text-slate-500 py-5 border-t border-white/5">
        © {new Date().getFullYear()} {tenant.name}
      </footer>
    </div>
  );
}

There are a few important details in this page worth calling out.

The generateMetadata function runs server-side before the page renders and sets the page title, description, and Open Graph tags for each tenant individually. This means every portfolio gets its own SEO metadata — important for a real SaaS product.

The sections object merges safe defaults (hero: true, skills: true, and so on) with whatever the tenant's template specifies. This means even if the template JSON is missing a key, the page won't break — the section will simply fall back to being shown.

The initials helper generates a two-letter avatar placeholder from the tenant's name when no profile image is available. "Jane Smith" produces "JS" — a small detail that makes the portfolio look polished even before a user adds a photo.

Notice that the primary color from the template JSON (theme.primaryColor) is applied using the style prop rather than a Tailwind class. This is intentional. Tailwind generates class names at build time and cannot know the dynamic color value stored in your database. Inline styles are the correct approach whenever a CSS value is truly dynamic.

How to Test the Full Flow

Start both servers in separate terminal windows:

# Terminal 1 — Backend
cd portfolio-api
npm run dev

# Terminal 2 — Frontend
cd portfolio-client
npm run dev

Now test the complete flow:

1. Visit http://localhost:3000 and fill out the form with your name, a short bio, and a comma-separated list of skills.

2. Click Create Portfolio. The form submits to your Express API, which creates the tenant record and returns the slug.

3. Your browser redirects to http://your-name.localhost:3000.

4. The Next.js middleware detects the subdomain, rewrites the request to /tenant/your-name, and your portfolio page fetches and renders your data.

You should see a fully rendered portfolio page with your name, bio, skills, and the placeholder projects and blog sections — all styled with Tailwind utility classes.

Next Steps

You now have a working multi-tenant SaaS foundation. Here are some extensions worth considering for a production build:

You could add authentication with NextAuth.js so tenants can log in and update their portfolio without losing their data between sessions.

You could also add custom domain support so tenants can point their own domain (for example, janedoe.com) to their portfolio by adding a CNAME record. You would need to handle wildcard SSL certificates on your hosting provider.

You could add image uploads for avatars using Cloudinary or AWS S3, then store the URL in the tenant record and replace the initials fallback with a real photo.

You could add real blog post management using the Post model already defined in your schema. Tenants could write and publish posts that appear on their portfolio.

And you could add Stripe subscriptions so tenants pay a monthly fee to keep their portfolio live. The architecture from the Stripe Connect tutorial maps directly onto this.

Finally, you could deploy the backend to Railway or Render and the frontend to Vercel. Just make sure to update your API URLs from localhost:8080 to your production URL before deploying.

Conclusion

In this tutorial, you built a complete multi-tenant SaaS platform where users can sign up, get their own subdomain, and have a portfolio site generated instantly — all from a single codebase.

You learned how to use Next.js middleware to detect subdomains and rewrite requests dynamically, model multi-tenant data in Prisma with a slug-based routing system, build a JSON-driven template system that controls page layout without code changes, and style a production-ready Next.js frontend entirely with Tailwind CSS utility classes.

The core insight is that multi-tenancy isn't magic. It's subdomain detection plus dynamic routing plus isolated data. Once you understand those three moving parts, you can apply this pattern to any SaaS product you build.

If you found this tutorial helpful, share it with someone who is learning to build full-stack applications. Happy coding!

Source Code

You can find the complete source code for both parts of this project on GitHub:

• Frontend (Next.js multi-tenant app) + Backend (Express + Prisma API): https://github.com/michaelokolo/portfolio-saas-v1

In this handbook, you'll build a complete marketplace from scratch using TypeScript. You won't need a traditional database. Instead, you'll use Stripe as your product catalog and payment engine.

This is how many real-world marketplaces work: Stripe stores the products, prices, and customer data, while your application handles the user experience.

Here's what you'll build:

1. A merchant onboarding flow where sellers create accounts and connect with Stripe

2. A product management system where merchants can add and list products directly through Stripe

3. A checkout flow that supports both one-time payments and recurring subscriptions

4. Webhooks that listen for payment events in real time

5. A billing portal where customers can manage their subscriptions

6. A complete storefront where customers can browse and buy products

You can also grab the complete source code from the GitHub repository linked at the end.

Table of Contents

• Prerequisites

• What is Stripe Connect?

• How to Set Up the Project

• How to Set Up the Backend

• How to Build the Express Backend

• How to Handle Merchant Onboarding

  • How to Create a Connected Account

  • How to Create the Onboarding Link

• How to Check Account Status

• How to Create Products Through Stripe

• How to Fetch Products

• How to Build the Checkout Flow

• How to Handle Webhooks

• How to Configure Webhooks in the Stripe Dashboard

• How to Test Webhooks Locally

• How to Add the Billing Portal

• How to Build the Next.js Frontend

• How to Create the Account Context

• How to Create the Account Status Hook

• How to Build the Merchant Onboarding Component

• How to Build the Product Create, Product List and Checkout

• How to Build the Product Form

• How to Build the Main Page

• How to Test the Full Flow

• How the Payment Split Works

• Next Steps

• Acknowledgements

• Conclusion

Prerequisites

Before you begin, make sure you have the following:

1. Node.js (version 18 or higher) installed on your machine

2. A basic understanding of React, TypeScript, and REST APIs

3. A Stripe account (sign up for free at stripe.com)

4. A code editor like VS Code

You do not need a database for this project. Stripe will store your products, prices, and customer information. This keeps the architecture simple and mirrors how many production marketplaces actually work.

What is Stripe Connect?

Stripe Connect is a set of APIs designed for platforms and marketplaces. It lets you create accounts for your merchants (Stripe calls them "connected accounts"), route payments to them, and take a platform fee on every transaction.

In this tutorial, you will use Stripe’s V2 Accounts API, which is the newer and recommended way to create connected accounts. With the V2 API, you configure what each account can do (accept card payments, receive payouts) through a configuration object, and Stripe handles all compliance and identity verification through a hosted onboarding flow.

Here's how the payment flow works:

1. A customer selects a product and clicks checkout on your marketplace.

2. Your server creates a Stripe Checkout Session linked to the merchant’s connected account.

3. The customer pays on Stripe’s hosted checkout page.

4. Stripe automatically splits the payment: the merchant gets their share, and your platform keeps an application fee.

5. Stripe sends a webhook event to your server confirming the payment.

6. The merchant can view their earnings and withdraw funds from their Stripe dashboard.

How to Set Up the Project

Create a project folder with separate directories for your backend and frontend:

mkdir marketplace && cd marketplace
mkdir server client

How to Set Up the Backend

Navigate into the server directory and initialize a TypeScript project:

cd server
npm init -y
npm install express cors dotenv stripe
npm install -D typescript ts-node @types/express @types/cors @types/node
npx tsc --init
mkdir src

Open tsconfig.json and update it with these settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"]
}

Then create a .env file in the server root:

STRIPE_SECRET_KEY=sk_test_your_key_here
DOMAIN=http://localhost:3000

You can find your Stripe test secret key in the Stripe Dashboard under Developers > API Keys. The DOMAIN variable tells your server where to redirect customers after checkout.

Add these scripts to your package.json:

{
  "scripts": {
    "dev": "ts-node src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

How to Build the Express Backend

Create the file src/index.ts. This will be your entire backend. Let’s start with the setup and imports:

import express, { Request, Response, Router } from 'express';
import cors from 'cors';
import dotenv from 'dotenv';
import Stripe from 'stripe';

dotenv.config();

const app = express();
const router = Router();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string);

app.use(cors({ origin: process.env.DOMAIN }));
app.use(express.static('public'));

Notice that we don't import any database client. Stripe is our data layer. Every product, price, customer, and transaction lives in Stripe. Your Express server is a thin orchestration layer that talks to the Stripe API on behalf of your frontend.

We also mount express.static("public") so you can serve static files later if needed. The webhook endpoint needs the raw request body, so we'll register it before the JSON parser. Let’s add that now.

How to Handle Merchant Onboarding

The first thing a merchant needs to do is create an account on your platform and connect it to Stripe. This involves two steps: creating a connected account, and then redirecting the merchant to Stripe’s hosted onboarding form.

How to Create a Connected Account

Add the following route to your src/index.ts:

// Type definitions for request bodies
interface CreateAccountBody {
  email: string;
}
interface AccountIdBody {
  accountId: string;
}

// Create a Connected Account using Stripe V2 API
router.post(
  '/create-connect-account',
  async (req: Request<{}, {}, CreateAccountBody>, res: Response) => {
    try {
      const account = await stripe.v2.core.accounts.create({
        display_name: req.body.email,
        contact_email: req.body.email,
        dashboard: 'full',
        defaults: {
          responsibilities: {
            fees_collector: 'stripe',
            losses_collector: 'stripe',
          },
        },
        identity: {
          country: 'GB',
          entity_type: 'company',
        },
        configuration: {
          customer: {},
          merchant: {
            capabilities: {
              card_payments: { requested: true },
            },
          },
        },
      });
      res.json({ accountId: account.id });
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

Let’s break down what this code does. The stripe.v2.core.accounts.create() method creates a new connected account using Stripe’s V2 API. Here are the key configuration options:

1. dashboard: "full" gives the merchant access to their own Stripe dashboard where they can view payments, manage payouts, and handle disputes.

2. responsibilities tells Stripe who collects fees and who is liable for losses. Setting both to "stripe" means Stripe handles this, which is the simplest configuration.

3. identity sets the country and entity type. Change "GB" to your merchants’ country code (for example, "US" for the United States).

4. configuration.merchant.capabilities requests the card_payments capability, which lets the merchant accept credit card payments.

How to Create the Onboarding Link

After creating the account, you need to redirect the merchant to Stripe’s hosted onboarding form. Add this route:

// Create Account Link for onboarding
router.post('/create-account-link', async (req: Request<{}, {}, AccountIdBody>, res: Response) => {
  const { accountId } = req.body;
  try {
    const accountLink = await stripe.v2.core.accountLinks.create({
      account: accountId,
      use_case: {
        type: 'account_onboarding',
        account_onboarding: {
          configurations: ['merchant', 'customer'],
          refresh_url: `${process.env.DOMAIN}`,
          return_url: `\({process.env.DOMAIN}?accountId=\){accountId}`,
        },
      },
    });
    res.json({ url: accountLink.url });
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

The accountLinks.create() method generates a temporary URL that takes the merchant to Stripe’s onboarding form. On that form, Stripe collects the merchant’s identity documents, bank account details, and tax information. You don't need to build any of this yourself.

The return_url is where Stripe redirects the merchant after they complete onboarding. Notice that you append the accountId as a query parameter so your frontend can pick it up and store it.

How to Check Account Status

You need a way to check whether a merchant has finished onboarding and is ready to accept payments. Add this route:

// Get Connected Account Status
router.get(
  '/account-status/:accountId',
  async (req: Request<{ accountId: string }>, res: Response) => {
    try {
      const account = await stripe.v2.core.accounts.retrieve(req.params.accountId, {
        include: ['requirements', 'configuration.merchant'],
      });
      const payoutsEnabled =
        account.configuration?.merchant?.capabilities?.stripe_balance?.payouts?.status === 'active';
      const chargesEnabled =
        account.configuration?.merchant?.capabilities?.card_payments?.status === 'active';
      const summaryStatus = account.requirements?.summary?.minimum_deadline?.status;
      const detailsSubmitted = !summaryStatus || summaryStatus === 'eventually_due';
      res.json({
        id: account.id,
        payoutsEnabled,
        chargesEnabled,
        detailsSubmitted,
        requirements: account.requirements?.entries,
      });
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

This route retrieves the connected account and checks three important statuses:

• chargesEnabled tells you if the merchant can accept payments.

• payoutsEnabled tells you if they can receive payouts to their bank account.

• detailsSubmitted tells you if they have completed the onboarding form.

Your frontend will use these flags to show or hide features.

How to Create Products Through Stripe

Instead of storing products in a database, you'll create them directly in Stripe. Each product is created on the merchant’s connected account using the stripeAccount header. This means each merchant has their own isolated product catalog inside Stripe.

// Type definition for product creation
interface CreateProductBody {
  productName: string;
  productDescription: string;
  productPrice: number;
  accountId: string;
}
// Create a product on the connected account
router.post('/create-product', async (req: Request<{}, {}, CreateProductBody>, res: Response) => {
  const { productName, productDescription, productPrice, accountId } = req.body;
  try {
    // Create the product on the connected account
    const product = await stripe.products.create(
      {
        name: productName,
        description: productDescription,
      },
      { stripeAccount: accountId },
    ); // Create a price for the product
    const price = await stripe.prices.create(
      {
        product: product.id,
        unit_amount: productPrice,
        currency: 'usd',
      },
      { stripeAccount: accountId },
    );
    res.json({
      productName,
      productDescription,
      productPrice,
      priceId: price.id,
    });
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

There are two Stripe API calls happening here. First, stripe.products.create() creates the product (name and description). Then stripe.prices.create() creates a price for that product (amount and currency).

Stripe separates products from prices because a single product can have multiple prices — for example, a monthly plan and an annual plan.

The { stripeAccount: accountId } option on both calls tells Stripe to create these resources on the merchant’s connected account, not on your platform account. This is a critical detail: without it, the products would be created on your platform’s account and the merchant would never see them.

How to Fetch Products

Add a route to list all products for a given merchant:

// Fetch products for a specific account
router.get('/products/:accountId', async (req: Request<{ accountId: string }>, res: Response) => {
  const { accountId } = req.params;
  try {
    const options: Stripe.RequestOptions = {};
    if (accountId !== 'platform') {
      options.stripeAccount = accountId;
    }
    const prices = await stripe.prices.list(
      {
        expand: ['data.product'],
        active: true,
        limit: 100,
      },
      options,
    );
    const products = prices.data.map((price) => {
      const product = price.product as Stripe.Product;
      return {
        id: product.id,
        name: product.name,
        description: product.description,
        price: price.unit_amount,
        priceId: price.id,
        period: price.recurring ? price.recurring.interval : null,
      };
    });
    res.json(products);
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

This route fetches all active prices from a merchant’s Stripe account and expands the product data (using expand: ["data.product"]) so you get the product name and description in the same API call. The period field will be null for one-time products and "month" or "year" for subscriptions.

How to Build the Checkout Flow

Your checkout flow needs to handle two scenarios: one-time payments for individual products, and recurring subscriptions. Stripe’s Checkout Sessions handle both — you just need to set the mode based on the price type.

// Type definition for checkout
interface CheckoutBody {
  priceId: string;
  accountId: string;
}
// Create checkout session
router.post(
  '/create-checkout-session',
  async (req: Request<{}, {}, CheckoutBody>, res: Response) => {
    const { priceId, accountId } = req.body;
    try {
      // Retrieve the price to determine if it is
      // one-time or recurring
      const price = await stripe.prices.retrieve(priceId, { stripeAccount: accountId });
      const isSubscription = price.type === 'recurring';
      const mode = isSubscription ? 'subscription' : 'payment';
      const session = await stripe.checkout.sessions.create(
        {
          line_items: [
            {
              price: priceId,
              quantity: 1,
            },
          ],
          mode,
          success_url: `${process.env.DOMAIN}/done?session_id={CHECKOUT_SESSION_ID}`,
          cancel_url: `${process.env.DOMAIN}`,
          ...(isSubscription
            ? {
                subscription_data: {
                  application_fee_percent: 10,
                },
              }
            : {
                payment_intent_data: {
                  application_fee_amount: 123,
                },
              }),
        },
        { stripeAccount: accountId },
      );
      res.redirect(303, session.url as string);
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

Here's what this route does step by step. First, it retrieves the price from the merchant’s connected account to check whether it is a one-time price or a recurring subscription. Then it creates a Checkout Session with the appropriate mode — either "payment" or "subscription".

The application_fee_amount is your platform’s cut of the transaction, specified in the smallest currency unit (cents for USD). In this example, you take $1.23 or 10% per transaction. For a real marketplace, you would likely calculate this as a percentage of the product price.

Notice that application_fee_amount goes inside subscription_data for subscriptions but inside payment_intent_data for one-time payments. This is a Stripe requirement — the two modes use different configuration objects.

Finally, the route uses res.redirect(303, session.url) to send the customer directly to Stripe’s hosted checkout page.

How to Handle Webhooks

Webhooks are how Stripe tells your server about events that happen asynchronously — like a successful payment, a failed charge, or a subscription cancellation.

In a production marketplace, you should never rely solely on redirect URLs to confirm payments. A customer might close their browser before the redirect completes. Webhooks are your source of truth.

Add the webhook endpoint before the JSON body parser. Stripe sends webhook payloads as raw bytes, and you need the raw body to verify the signature:

// IMPORTANT: Register this BEFORE app.use(express.json())
app.post(
  '/api/webhook',
  express.raw({ type: 'application/json' }),
  (req: Request, res: Response) => {
    let event: Stripe.Event = JSON.parse(req.body.toString()); // If you have an endpoint secret, verify the
    // signature for security
    const endpointSecret = process.env.WEBHOOK_SECRET;
    if (endpointSecret) {
      const signature = req.headers['stripe-signature'] as string;
      try {
        event = stripe.webhooks.constructEvent(req.body, signature, endpointSecret) as Stripe.Event;
      } catch (err) {
        const message = err instanceof Error ? err.message : 'Unknown error';
        console.log('Webhook signature verification failed:', message);
        res.sendStatus(400);
        return;
      }
    } // Handle the event
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Payment successful for session:', session.id); // Fulfill the order: send email, grant access,
        // update your records, and so on
        break;
      }
      case 'checkout.session.expired': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Session expired:', session.id); // Optionally notify the customer or clean up
        // any pending records
        break;
      }
      case 'checkout.session.async_payment_succeeded': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Delayed payment succeeded for session:', session.id); // Fulfill the order now that payment cleared
        break;
      }
      case 'checkout.session.async_payment_failed': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Payment failed for session:', session.id); // Notify the customer that payment failed
        break;
      }
      case 'customer.subscription.deleted': {
        const subscription = event.data.object as Stripe.Subscription;
        console.log('Subscription cancelled:', subscription.id); // Revoke access for the customer
        break;
      }
      default:
        console.log('Unhandled event type:', event.type);
    }
    res.send();
  },
);

The webhook handler checks for five key events.

• checkout.session.completed fires when a payment succeeds — this is where you would fulfill an order, send a confirmation email, or grant access.

• checkout.session.expired fires when a session expires before the customer completes payment.

• checkout.session.async_payment_succeeded fires when a delayed payment method (like a bank transfer) finally goes through.

• checkout.session.async_payment_failed fires when a delayed payment method fails.

• And customer.subscription.deleted fires when a subscription is cancelled.

How to Configure Webhooks in the Stripe Dashboard

Before you can receive webhook events, you need to tell Stripe where to send them and which events you care about. Follow these steps:

1. Go to the Stripe Dashboard and navigate to Developers > Webhooks.

2. Click "Add destination."

3. Under the account type, select "Connected and V2 accounts" since your payments go through connected merchant accounts.

4. Under "Events to listen for," click "All events" and select the following five events:

   • checkout.session.async_payment_succeeded — Occurs when a payment intent using a delayed payment method finally succeeds.

   • checkout.session.completed — Occurs when a Checkout Session has been successfully completed.

   • checkout.session.expired — Occurs when a Checkout Session expires before completion.

   • checkout.session.async_payment_failed — Occurs when a payment intent using a delayed payment method fails.

   • customer.subscription.deleted — Occurs whenever a customer’s subscription ends.

5. Enter your webhook endpoint URL. For production, this would be something like https://yourdomain.com/api/webhook. For local development, you will use the Stripe CLI instead (covered next).

6. Click "Add destination" to save.

How to Test Webhooks Locally

For local development, you don't need to expose your server to the internet. Install the Stripe CLI and run:

brew install stripe/stripe-cli/stripe
stripe login
stripe listen --forward-to localhost:4242/webhook

The CLI will print a webhook signing secret that starts with whsec_. Add this to your .env file as WEBHOOK_SECRET. The CLI intercepts all webhook events from Stripe and forwards them to your local server, so you can test the full payment flow without deploying anything.

How to Add the Billing Portal

The billing portal lets customers manage their subscriptions without you building any UI for it. Stripe hosts the entire experience — customers can update their payment method, change plans, or cancel their subscription.

// Create a billing portal session
router.post(
  "/create-portal-session",
  async (req: Request, res: Response) => {
    const { session_id } = req.body as {
      session_id: string;
    };
 
    try {
      const session =
        await stripe.checkout.sessions.retrieve(
          session_id
        );
 
      const portalSession =
        await stripe.billingPortal.sessions.create({
          customer_account: session.customer_account as string,
          return_url: `\({process.env.DOMAIN}?session_id=\){session_id}`,
        });
 
      res.redirect(303, portalSession.url);
    } catch (error) {
      const message =
        error instanceof Error
          ? error.message
          : "Unknown error";
      res.status(500).json({ error: message });
    }
  }
);

This route takes a session_id from a previous checkout, retrieves the associated customer, and creates a billing portal session. The customer_account field links the portal to the correct connected account so the customer sees only their subscriptions with that specific merchant.

Now add the JSON parser and mount the router. This must come after the webhook route:

// JSON and URL-encoded parsers (AFTER webhook route)
app.use(express.urlencoded({ extended: true }));
app.use(express.json());

// Mount all routes under /api
app.use('/api', router);
const PORT: number = parseInt(process.env.PORT || '4242', 10);
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

How to Build the Next.js Frontend

Navigate to the client directory and create a new Next.js project with TypeScript:

cd ../client
npx create-next-app@latest . --typescript --app --tailwind --eslint
npm install axios

How to Create the Account Context

You need a way to share the merchant’s account ID across all components. Create a context provider at contexts/AccountContext.tsx:

'use client';
import { createContext, useContext, useState, ReactNode } from 'react';
import { useSearchParams } from 'next/navigation';

interface AccountContextType {
  accountId: string | null;
  setAccountId: (id: string | null) => void;
}

const AccountContext = createContext<AccountContextType | undefined>(undefined);

export function useAccount(): AccountContextType {
  const context = useContext(AccountContext);
  if (!context) {
    throw new Error('useAccount must be used within AccountProvider');
  }
  return context;
}

export function AccountProvider({ children }: { children: ReactNode }) {
  const searchParams = useSearchParams();
  const [accountId, setAccountId] = useState<string | null>(searchParams.get('accountId'));

  return (
    <AccountContext.Provider value={{ accountId, setAccountId }}>
      {children}
    </AccountContext.Provider>
  );
}

This context stores the current merchant’s account ID and makes it available throughout the app. On initial load, it checks the URL for an accountId query parameter — this is how Stripe’s onboarding redirect passes the account ID back to your app.

How to Create the Account Status Hook

Create a custom hook at hooks/useAccountStatus.ts that polls the account status:

'use client';
import { useState, useEffect } from 'react';
import { useAccount } from '@/contexts/AccountContext';
interface AccountStatus {
  id: string;
  payoutsEnabled: boolean;
  chargesEnabled: boolean;
  detailsSubmitted: boolean;
}
export default function useAccountStatus() {
  const [accountStatus, setAccountStatus] = useState<AccountStatus | null>(null);
  const { accountId, setAccountId } = useAccount();
  useEffect(() => {
    if (!accountId) return;
    const fetchStatus = async () => {
      try {
        const res = await fetch(`http://localhost:4242/api/account-status/${accountId}`);
        if (!res.ok) throw new Error('Failed to fetch');
        const data: AccountStatus = await res.json();
        setAccountStatus(data);
      } catch {
        setAccountId(null);
      }
    };
    fetchStatus();
    const interval = setInterval(fetchStatus, 5000);
    return () => clearInterval(interval);
  }, [accountId, setAccountId]);
  return {
    accountStatus,
    needsOnboarding: !accountStatus?.chargesEnabled && !accountStatus?.detailsSubmitted,
  };
}

This hook polls the account status every 5 seconds. This is important because Stripe’s onboarding is asynchronous — a merchant might complete the form, but it can take a moment for Stripe to verify their details and activate their account. The needsOnboarding flag tells your UI whether to show the onboarding button or the merchant dashboard.

How to Build the Merchant Onboarding Component

Create components/ConnectOnboarding.tsx:

'use client';
import { useState } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
export default function ConnectOnboarding() {
  const [email, setEmail] = useState<string>('');
  const { accountId, setAccountId } = useAccount();
  const { accountStatus, needsOnboarding } = useAccountStatus();
  const handleCreateAccount = async () => {
    const res = await fetch(`${API_URL}/create-connect-account`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    });
    const data = await res.json();
    setAccountId(data.accountId);
  };
  const handleStartOnboarding = async () => {
    const res = await fetch(`${API_URL}/create-account-link`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ accountId }),
    });
    const data = await res.json();
    window.location.href = data.url;
  };
  if (!accountId) {
    return (
      <div className="max-w-md mx-auto p-6">
        <h2 className="text-xl font-bold mb-4">Create Your Seller Account</h2>
        <input
          type="email"
          placeholder="Your email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          className="w-full border p-2 rounded mb-4"
        />
        <button
          onClick={handleCreateAccount}
          className="w-full bg-green-600 text-white p-2 rounded hover:bg-green-700"
        >
          Create Connect Account
        </button>
      </div>
    );
  }
  return (
    <div className="max-w-md mx-auto p-6">
      <h3 className="font-semibold mb-2">Account: {accountId} </h3>
      <p className="mb-2">Charges: {accountStatus?.chargesEnabled ? 'Active' : 'Pending'} </p>
      <p className="mb-4">Payouts: {accountStatus?.payoutsEnabled ? 'Active' : 'Pending'} </p>
      {needsOnboarding && (
        <button
          onClick={handleStartOnboarding}
          className="bg-purple-600 text-white px-6 py-2 rounded hover:bg-purple-700"
        >
          Complete Onboarding
        </button>
      )}
    </div>
  );
}

This component handles both states of the merchant experience. If no account exists, it shows a simple email form. After account creation, it shows the account status and an onboarding button if needed.

How to Build the Product Create, Product List and Checkout

Create components/Products.tsx:

'use client';
import { useState, useEffect } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
interface Product {
  id: string;
  name: string;
  description: string | null;
  price: number | null;
  priceId: string;
  period: string | null;
}
export default function Products() {
  const { accountId } = useAccount();
  const { needsOnboarding } = useAccountStatus();
  const [products, setProducts] = useState<Product[]>([]);
  useEffect(() => {
    if (!accountId || needsOnboarding) return;
    const fetchProducts = async () => {
      const res = await fetch(`\({API_URL}/products/\){accountId}`);
      const data: Product[] = await res.json();
      setProducts(data);
    };
    fetchProducts();
    const interval = setInterval(fetchProducts, 5000);
    return () => clearInterval(interval);
  }, [accountId, needsOnboarding]);
  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mt-6">
      {' '}
      {products.map((product) => (
        <div key={product.priceId} className="border rounded-lg p-4 shadow-sm">
          <h3 className="text-lg font-semibold">  {product.name}</h3>

          <p className="text-gray-600 mt-1">  {product.description}</p>

          <p className="text-xl font-bold mt-3">
            ${((product.price ?? 0) / 100).toFixed(2)}
            {product.period ? ` / ${product.period}` : ''}
          </p>

          <form action={`${API_URL}/create-checkout-session`} method="POST">
            <input type="hidden" name="priceId" value={product.priceId} />
            <input type="hidden" name="accountId" value={accountId ?? ''} />
            <button
              type="submit"
              className="mt-4 w-full bg-blue-600 text-white py-2 rounded hover:bg-blue-700"
            >
              {product.period ? 'Subscribe' : 'Buy Now'}
            </button>
          </form>
        </div>
      ))}
    </div>
  );
}

The Products component fetches all products from the merchant’s Stripe account and displays them in a responsive grid. The checkout button submits a form directly to your backend, which redirects the customer to Stripe’s hosted checkout page. Notice how the button text changes based on whether the product is a one-time purchase or a subscription.

How to Build the Product Form

Merchants need a way to add products from the frontend. Create components/ProductForm.tsx:

'use client';
import { useState } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
interface ProductFormData {
  productName: string;
  productDescription: string;
  productPrice: number;
}
export default function ProductForm() {
  const { accountId } = useAccount();
  const { needsOnboarding } = useAccountStatus();
  const [showForm, setShowForm] = useState<boolean>(false);
  const [formData, setFormData] = useState<ProductFormData>({
    productName: '',
    productDescription: '',
    productPrice: 1000,
  });
  const handleSubmit = async (e: React.FormEvent): Promise<void> => {
    e.preventDefault();
    if (!accountId || needsOnboarding) return;
    await fetch(`${API_URL}/create-product`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        ...formData,
        accountId,
      }),
    }); // Reset form and hide it
    setFormData({
      productName: '',
      productDescription: '',
      productPrice: 1000,
    });
    setShowForm(false);
  }; // Only show the form if the merchant has completed
  // onboarding and can accept charges
  if (!accountId || needsOnboarding) return null;
  return (
    <div className="my-6">
      <button
        onClick={() => setShowForm(!showForm)}
        className="bg-green-600 text-white px-4 py-2 rounded hover:bg-green-700"
      >
        {showForm ? 'Cancel' : 'Add New Product'}
      </button>

      {showForm && (
        <form onSubmit={handleSubmit} className="mt-4 max-w-md space-y-4">
          <div>
            <label className="block text-sm font-medium mb-1">Product Name</label>

            <input
              type="text"
              value={formData.productName}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productName: e.target.value,
                })
              }
              className="w-full border p-2 rounded"
              required
            />
          </div>

          <div>
            <label className="block text-sm font-medium mb-1">Description</label>
            <input
              type="text"
              value={formData.productDescription}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productDescription: e.target.value,
                })
              }
              className="w-full border p-2 rounded"
            />
          </div>
          <div>
            <label className="block text-sm font-medium mb-1">Price (in cents)</label>

            <input
              type="number"
              value={formData.productPrice}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productPrice: parseInt(e.target.value),
                })
              }
              className="w-full border p-2 rounded"
              required
            />
          </div>
          <button
            type="submit"
            className="bg-blue-600 text-white px-4 py-2 rounded hover:bg-blue-700"
          >
            Create Product
          </button>
        </form>
      )}
    </div>
  );
}

This component only renders after the merchant has completed onboarding (the if (!accountId || needsOnboarding) return null check at the top). It toggles a form where the merchant enters a product name, description, and price in cents. When submitted, it calls your /api/create-product endpoint, which creates both the product and its price on the merchant’s connected Stripe account.

The price field uses cents because that is what Stripe expects. So if a merchant wants to sell a product for \(25.00, they enter 2500. In a production app, you would add a friendlier input that lets merchants type \)25.00 and converts it to cents automatically.

How to Build the Main Page

Finally, put it all together in app/page.tsx:

'use client';
import { AccountProvider } from '@/contexts/AccountContext';
import ConnectOnboarding from '@/components/ConnectOnboarding';
import Products from '@/components/Products';
import ProductForm from '@/components/ProductForm';
export default function Home() {
  return (
    <AccountProvider>
      {' '}
      <main className="max-w-6xl mx-auto p-8">
        <h1 className="text-3xl font-bold mb-8"> Marketplace Dashboard </h1>
        <ConnectOnboarding />
        <ProductForm />
        <Products />
      </main>
    </AccountProvider>
  );
}

How to Test the Full Flow

Start both servers:

# Terminal 1 - Backend
cd server
npm run dev
 
# Terminal 2 - Frontend
cd client
npm run dev
 
# Terminal 3 - Stripe webhook listener
stripe listen --forward-to localhost:4242/api/webhook

Now test the complete flow:

1. Go to http://localhost:3000 and enter an email to create a merchant account.

2. Click "Complete Onboarding" and fill out Stripe’s test onboarding form. Use test data like 000-000-0000 for the phone number and 0000 for the last four digits of SSN.

3. Wait a few seconds for the account status to update. Once charges are active, you can add products.

4. Create a product using the product form (set the price in cents — for example, 2500 for $25.00).

5. Click "Buy Now" on a product to start the checkout flow.

6. On Stripe’s checkout page, use the test card number 4242 4242 4242 4242 with any future expiry date and any CVC.

7. Check your terminal — you should see the webhook event confirming the payment.

8. Check the Stripe Dashboard to see the payment, the application fee, and the transfer to the connected account.

How the Payment Split Works

Here is exactly what happens when a customer pays $25.00 for a product:

1. The customer pays $25.00 on Stripe’s checkout page.

2. Stripe deducts its processing fee (approximately 2.9% + $0.30 for US cards).

3. Your platform takes the application fee you set ($1.23 in our example).

4. The remaining amount is transferred to the merchant’s connected Stripe account.

5. The merchant can withdraw their funds to their bank account from the Stripe Dashboard.

You control the application fee in the checkout route. In a production marketplace, you would calculate this as a percentage of the transaction. For example, to take a 10% fee:

onst applicationFee = Math.round(
  (price.unit_amount ?? 0) * 0.1
);

Next Steps

You now have a working marketplace. Here are improvements to consider for production:

• Add authentication with NextAuth.js so merchants can securely log in and manage their accounts across sessions.

• Add runtime validation with Zod to validate all request bodies before they reach Stripe.

• Add image uploads for products using Cloudinary or AWS S3, then pass the image URL to Stripe’s product metadata.

• Build separate merchant and customer views. Right now the app combines both experiences on one page.

• Deploy your backend to Railway or Render and your frontend to Vercel. Update the webhook URL in your Stripe Dashboard to point to your production server.

You can find the complete source code for this tutorial on GitHub: https://github.com/michaelokolo/marketplace

Acknowledgements

Some API usage patterns in this tutorial are inspired by examples from the official Stripe documentation. These examples were adapted to demonstrate how to build a complete multi-vendor marketplace architecture.

Conclusion

In this handbook, you built a complete online marketplace where merchants can onboard through Stripe Connect, create products stored directly in Stripe, and receive payments from customers — all without a traditional database.

You learned how to use Stripe’s V2 Accounts API for merchant onboarding, create products and prices on connected accounts, build a checkout flow that handles both one-time payments and subscriptions, listen for payment events with webhooks, and give customers a billing portal to manage their subscriptions.

The key insight is that Stripe Connect handles the hardest parts of running a marketplace — payment splitting, tax compliance, identity verification, and fund transfers. Your job is to build a great user experience on top of it.

If you found this tutorial helpful, share it with someone who is learning to build full-stack applications. Happy coding!