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!

Before we begin, you should be familiar with the basics of React.js and Next.js to get the most out of this guide.

If you're not and need to brush up, I recommend you go through the ReactJS and NextJS documentation.

The stack we will use:

1. ReactJS is a JavaScript library for building user interfaces. It is declarative and component-based.

2. NextJS is a React-based framework that lets us render data on the server side. It helps Google crawl the application which results in SEO benefits.

3. PlanetScale is a database as a service that is developed on Vitess, an open-source technology that powers YouTube and uses MySQL internally.

4. TailwindCSS is a utility-first CSS framework packed with classes that can be composed to build any design, directly in our markup.

5. Prisma is an ORM built for NodeJS and TypeScript which handles automated migrations, type-safety, and auto-completion.

6. Vercel will host our application. It scales well, all without any configuration, and deployment is instant.

7. Stripe is a payment gateway, and we will use it to accept online payments on the website.

Table of Contents

1. How to Configure PlanetScale, Stripe, NextJS, Prisma and Other Libraries

2. How to Implement Mock Data, Category-Products API and All Category-Single Category UI

3. How to Implement Single Product UI and Stripe Checkout

4. How to Deploy the Website to Production

I am going to divide this tutorial into four separate sections.

At the start of every section, you will find a Git commit that has the code developed in that section. Also, if you want to see the complete code, then it is available in this repository.

How to Configure PlanetScale, Stripe, NextJS, TailwindCSS, and Prisma.

In this section, we'll implement the following functionality:

1. Create a PlanetScale Account and Database.

2. Create a Stripe Account.

3. Configure NextJS, TailwindCSS, and Prisma.

You can find the eCommerce website code implemented in this section at this commit.

How to Configure PlanetScale:

To create a PlanetScale account, visit this URL. Click on Get started button at the top right corner.

PlanetScale Landing Page

You can either create an account using GitHub or a traditional email-password. Once the account is created, then click on the "create" link.

PlanetScale Dashboard Page

You'll receive the following modal:

PlanetScale New Database Modal

Fill in the details and click on the Create database button. Once the database is created you'll be redirected to the following page:

PlanetScale Ecommerce Website Database Page

Click on connect and a modal will open. This modal will contain a Database URL and this password cannot be generated again. So copy and paste it into a safe location.

PlanetScale Database Username and Password Modal

How to Configure Stripe:

To create a Stripe account, go to this URL. Once you've created the account, click on the Developer Button from the Nav menu. You'll see API keys on the left side and you'll find the Publishable key and Secret key under Standard keys.

Publishable key: These are the keys that can be publicly-accessible in a web or mobile app’s client-side code.

Secret key: This is a secret credential and should be securely stored in the server code. This key is used to call the Stripe API.

How to Configure NextJS, TailwindCSS, and Prisma.

First, we will create a NextJS app using the following command:

npx create-next-app ecommerce-tut --ts --use-npm

Once the project is created, open it with your favourite editor. You'll get the following structure:

Project Structure

Let's create a directory named src. We will move the pages and styles directory to that src folder. You'll get the following structure:

Project Structure after moving Pages and Styles.

Install the following packages:

npm i @ngneat/falso @prisma/client @stripe/stripe-js @tanstack/react-query currency.js next-connect react-icons react-intersection-observer stripe

We also need to install dev dependencies:

npm i --save-dev @tanstack/react-query-devtools autoprefixer postcss tailwindcss

Let's understand each of the packages:

1. @ngneat/falso: We will use this library to create mock data for our eCommerce website. In an ideal world, you would have an admin panel to add the products, but it is not in the scope of this tutorial.

2. @prisma/client: We will use this library to connect to our database, run migrations, and do all CRUD operations on the database.

3. @stripe/stripe-js: We will use this library to redirect users to the stripe checkout page and process payment.

4. @tanstack/react-query: We will use this library for managing our asynchronous state, that is caching API responses.

5. currency.js: We will use this library for converting our prices to two decimal format.

6. next-connect: We will use this library for routing purposes on our Next API layer.

7. react-icons: We will use this library for adding icons to our buttons and links.

8. react-intersection-observer: Have you seen infinite scrolling on a lot of websites and wondered how it is implemented? We will use this library to implement that based on the viewport.

9. stripe: We will use the Stripe library to connect with Stripe API from our Next API layer.

10. @tanstack/react-query-devtools: We will use this library as the only dev dependency to view and manage our cache during development time.

11. TailwindCSS: We will use this as our CSS library that also requires PostCSS and AutoPrefixer.

Let's configure TailwindCSS into our project using the following command:

npx tailwindcss init -p

You'll get the following response:

TailwindCSS Config Success

Now go to tailwind.config.js and update it with the following code:

/** @type {import('tailwindcss').Config} */
module.exports = {
    content: [
        "./src/pages/**/*.{js,ts,jsx,tsx}",
        "./src/components/**/*.{js,ts,jsx,tsx}",
    ],
    theme: {
        extend: {},
    },
    plugins: [],
};

To generate the CSS, Tailwind needs access to all the HTML Elements. We will be writing the UI components under pages and components only, so we pass it under content.

If you need to use any plugins, for example, typography, then you need to add them under the plugins array. If you need to extend the default theme provide by Tailwind, then you need to add it under theme.extend section.

Now go to /src/styles/globals.css and replace the existing code with the following:

@tailwind base;
@tailwind components;
@tailwind utilities;

We will add these three directives in our globals.css file. The meaning of each directive is as follows:

1. @tailwind base: This injects a base style provided by Tailwind.

2. @tailwind components: This injects classes and any other classes added by the plugin.

3. @tailwind utilities: This injects hover, focus, responsive, dark mode and any other utility added by the plugin.

Remove the Home.module.css from src/styles directory and go to src/pages/index.ts and replace the existing code with the following:

import type { NextPage } from "next";
import Head from "next/head";

const Home: NextPage = () => {
    return (
        <div>
            <Head>
                <title>All Products</title>
                <meta name="description" content="All Products" />
                <link rel="icon" href="/favicon.ico" />
            </Head>

            <main className="container mx-auto">
                <h1 className="h-1">Hello</h1>
            </main>
        </div>
    );
};

export default Home;

When we run the create-next-app command to create the project, it adds some boilerplate code. Here we removed that in some instances while replacing index.ts with an h1 and text that says "Hello".

It's time to run the website using the following command:

npm run dev

You'll get the following response:

Open http://localhost:3000 on your browser, and you'll get the following screen with a hello message:

Screen with Hello Message

Let's configure Prisma into our project using the following command:

npx prisma init

You'll get the following response:

Prisma Successfully Configured Message

Under prisma/schema.prisma replace the existing code with the following code:

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["referentialIntegrity"]
}

datasource db {
  provider             = "mysql"
  url                  = env("DATABASE_URL")
  referentialIntegrity = "prisma"
}

model Category {
  id        String    @id @default(cuid())
  name      String    @unique
  createdAt DateTime  @default(now())
  products  Product[]
}

model Product {
  id          String    @id @default(cuid())
  title       String    @unique
  description String
  price       String
  quantity    Int
  image       String
  createdAt   DateTime  @default(now())
  category    Category? @relation(fields: [categoryId], references: [id])
  categoryId  String?
}

This file consists of our database source that is MySQL. We are using MySQL because PlanetScale supports MySQL only.

Also, we have created two models that are:

Category:

1. name: Every category will have a unique title.

2. createdAt: The date when a category is added.

3. products: A foreign relationship with the product model.

Product:

1. title: Every product will have a unique title.

2. description: This is just information about the product.

3. price: It is of String type because it will hold a decimal value.

4. quantity: It is of Int type because it will hold a numerical value.

5. image: Representation of what the product will look like. We will use placeimg for the purpose of this tutorial.

6. createdAt: The date when a product is added.

7. category: A foreign relationship with the category model.

We are using cuid() instead of uuid() for the id because they are better for horizontal scaling and sequential lookup performance. Prisma has inbuilt support for CUID. You can read more about it here.

Now time to update our .env file with the following:

DATABASE_URL=

STRIPE_SECRET_KEY=

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

You'll find the Stripe secret key and publishable key under the dashboard. The database URL is the one that we had copy-pasted earlier and kept in a safe location. Update this .env with those credentials.

Also, note that the .gitignore file created by NextJS doesn't ignore the .env file. It is configured to ignore the .env.local file. But Prisma requires .env, so we will replace the .gitignore file content with the following:

# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.

# dependencies
/node_modules
/.pnp
.pnp.js

# testing
/coverage

# next.js
/.next/
/out/

# production
/build

# misc
.DS_Store
*.pem

# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.pnpm-debug.log*

# local env files
.env
.env*.local

# vercel
.vercel

# typescript
*.tsbuildinfo
next-env.d.ts

Ideally, Prisma manages schema migration using the prisma migrate command. But as PlanetScale has its schema migration mechanism inbuilt, we will use that. Use the following command to push migration to our current main branch.

Note, our main branch is not yet promoted as a production branch.

npx prisma db push

Now let's generate the Prisma client using the following command:

npx prisma generate

Go to the PlanetScale Dashboard, and there you'll find two tables created:

PlanetScale Two Tables Created

Click on these tables, and you'll be redirected to the following page:

PlanetScale Database Schema

How to Implement Mock Data, Category-Products API, and All Category-Single Category UI.

In this section, we'll implement the following functionality:

1. Create mock data

2. Create a Category and Product API.

3. Create an All Category and Single Category UI.

You can find the eCommerce website code implemented in this section at this commit.

How to Create the Mock Data:

Under the prisma directory, create a file named seed.ts and copy-paste the following code:

import {
    randBetweenDate,
    randNumber,
    randProduct,
    randProductAdjective,
} from "@ngneat/falso";
import { PrismaClient } from "@prisma/client";

const primsa = new PrismaClient();

const main = async () => {
    try {
        await primsa.category.deleteMany();
        await primsa.product.deleteMany();
        const fakeProducts = randProduct({
            length: 1000,
        });
        for (let index = 0; index < fakeProducts.length; index++) {
            const product = fakeProducts[index];
            const productAdjective = randProductAdjective();
            await primsa.product.upsert({
                where: {
                    title: `${productAdjective} ${product.title}`,
                },
                create: {
                    title: `${productAdjective} ${product.title}`,
                    description: product.description,
                    price: product.price,
                    image: `${product.image}/tech`,
                    quantity: randNumber({ min: 10, max: 100 }),
                    category: {
                        connectOrCreate: {
                            where: {
                                name: product.category,
                            },
                            create: {
                                name: product.category,
                                createdAt: randBetweenDate({
                                    from: new Date("10/06/2020"),
                                    to: new Date(),
                                }),
                            },
                        },
                    },
                    createdAt: randBetweenDate({
                        from: new Date("10/07/2020"),
                        to: new Date(),
                    }),
                },
                update: {},
            });
        }
    } catch (error) {
        throw error;
    }
};

main().catch((err) => {
    console.warn("Error While generating Seed: \n", err);
});

Here we are creating 1000 fake products and adding them to the database.

We are following these steps to add the products:

1. Delete all the categories using the deleteMany() function.

2. Delete all the product using the deleteMany() function.

3. The above are optional steps, but it's always a good idea to rerun the seed script with a clean table.

4. As the title attribute from the product table has unique property associated with it we bind it with the randProductAdjective function output to make repetitions less likely.

5. But still, there is a probability that the title property created by the falso gets repeated. So we use the upsert method from @prisma/client.

6. We are also creating/associating the category when we create a product.

Now go to package.json and update the following code below scripts:

"prisma": {
    "seed": "ts-node --compiler-options {\"module\":\"CommonJS\" prisma/seed.ts"
},

We will use the ts-node package to run our seed script command. The seed script is written in TypeScript while ts-node converts TypeScript code to JavaScript.

Use the following command to install the package:

npm i --save-dev ts-node

As the ts-node will convert the code to JavaScript, we can execute the following command to seed the tables with mock data:

npx prisma db seed

You'll get the following output that will show it has started running. It will take some time to seed the tables with mock data.

Once the seed command is successful, you'll get the following response:

The benefit of Prisma is that it also has a studio, which can be used to view the database in a local development environment. Use the following command to run this studio:

npx prisma studio

Open http://localhost:5555, on your browser, and you'll get the following screen with all the tables:

Prisma Studio

The number of Products and Categories may vary on your side or be similar, as this is random data.

How to Create the Category and Product APIs:

Under the src/pages/api category you'll find a file named hello.ts. Remove this file and create two directories named categories and products.

Inside those categories, create a file named index.ts and copy-paste the following code:

import type { NextApiRequest, NextApiResponse } from "next";
import nc from "next-connect";
import { prisma } from "../../../lib/prisma";
import { TApiAllCategoriesResp, TApiErrorResp } from "../../../types";

const getCategories = async (
    _req: NextApiRequest,
    res: NextApiResponse<TApiAllCategoriesResp | TApiErrorResp>
) => {
    try {
        const categories = await prisma.category.findMany({
            select: {
                id: true,
                name: true,
                products: {
                    orderBy: {
                        createdAt: "desc",
                    },
                    take: 8,
                    select: {
                        title: true,
                        description: true,
                        image: true,
                        price: true,
                    },
                },
            },
            orderBy: {
                createdAt: "desc",
            },
        });
        return res.status(200).json({ categories });
    } catch (error) {
        return res.status(500).json({
            message: "Something went wrong!! Please try again after sometime",
        });
    }
};

const handler = nc({ attachParams: true }).get(getCategories);

export default handler;

In the above snippet, we are doing the following:

1. When we create a file under the pages>api directory, NextJS treats it as a Serverless API. So by creating a file named categories/index.ts we are informing Next that it needs to convert this to the /api/categories API.

2. Using the next-connect library we are making sure that only the get operation is allowed for the getCategories function.

3. Under this function, we are querying the database with an order as desc for the createdAt property and we only take the latest eight product rows for each category row. We also select a specific property from the product and category that are required by the front end.

We don't query all the products for each category in this API, because it will slow down our response time.

You'll find that we have imported prisma and types files. Let's create two directories under src named lib and types.

Under the lib directory, create a file named prisma.ts, and under the types directory create a file named index.ts.

Let's create our global Prisma constant under prisma.ts. Copy-paste the following code:

import { PrismaClient } from "@prisma/client";

declare global {
    var prisma: PrismaClient;
}

export const prisma =
    global.prisma ||
    new PrismaClient({
        log: [],
    });

if (process.env.NODE_ENV !== "production") global.prisma = prisma;

Here we are creating a global prisma variable which we can use across the project.

Let's add the types that we will use application-wide under src/types/index.ts.

Copy-paste the following code:

export type TApiAllCategoriesResp = {
    categories: {
        id: string;
        name: string;
        products: {
            title: string;
            description: string;
            image: string;
            price: string;
        }[];
    }[];
};

export type TApiSingleCategoryWithProductResp = {
    category: {
        id: string;
        name: string;
        products: {
            id: string;
            title: string;
            description: string;
            image: string;
            price: string;
            quantity: number;
        }[];
        hasMore: boolean;
    };
};

export type TApiSingleProductResp = {
    product: {
        title: string;
        description: string;
        price: string;
        quantity: number;
        image: string;
    };
};

export type TApiErrorResp = {
    message: string;
};

Here we are creating four types which will be used across the project.

I'll be using Postman to test this API. Postman is a utility for developing APIs. You can call the APIs, and Postman will show the response based on how you structure it.

Just update the URL in Postman to:

http://localhost:3000/api/categories

And you'll get the following response:

All Categories Resp

Now let's create an API to get a single category's information with its products.

Under the src/pages/api/categories directory create a file named [id].ts and copy-paste the following code:

import type { NextApiRequest, NextApiResponse } from "next";
import nc from "next-connect";
import { prisma } from "../../../lib/prisma";
import {
    TApiErrorResp,
    TApiSingleCategoryWithProductResp
} from "../../../types";

const getSingleCategory = async (
    req: NextApiRequest,
    res: NextApiResponse<TApiSingleCategoryWithProductResp | TApiErrorResp>
) => {
    try {
        const id = req.query.id as string;
        const cursorId = req.query.cursorId;
        if (cursorId) {
            const categoriesData = await prisma.category.findUnique({
                where: {
                    id,
                },
                select: {
                    id: true,
                    name: true,
                    products: {
                        orderBy: {
                            createdAt: "desc",
                        },
                        take: 12,
                        skip: 1,
                        cursor: {
                            id: cursorId as string,
                        },
                        select: {
                            id: true,
                            title: true,
                            description: true,
                            image: true,
                            price: true,
                            quantity: true,
                        },
                    },
                },
            });

            if (!categoriesData) {
                return res.status(404).json({ message: `Category not found` });
            }

            let hasMore = true;
            if (categoriesData.products.length === 0) {
                hasMore = false;
            }

            return res
                .status(200)
                .json({ category: { ...categoriesData, hasMore } });
        }

        const categoriesData = await prisma.category.findUnique({
            where: {
                id,
            },
            select: {
                id: true,
                name: true,
                products: {
                    orderBy: {
                        createdAt: "desc",
                    },
                    take: 12,
                    select: {
                        id: true,
                        title: true,
                        description: true,
                        image: true,
                        price: true,
                        quantity: true,
                    },
                },
            },
        });
        if (!categoriesData) {
            return res.status(404).json({ message: `Category not found` });
        }

        let hasMore = true;
        if (categoriesData.products.length === 0) {
            hasMore = false;
        }

        return res
            .status(200)
            .json({ category: { ...categoriesData, hasMore } });
    } catch (error) {
        return res.status(500).json({
            message: "Something went wrong!! Please try again after sometime",
        });
    }
};

const handler = nc({ attachParams: true }).get(getSingleCategory);

export default handler;

In the above snippet, we are doing the following:

1. By creating a file named [id].ts under src/pages/api/categories we are telling NextJS to convert this to the /api/categories/[id] API.

2. The [id] is the category id from the category table.

3. Using the next-connect library we are making sure that only the get operation is allowed for the getSingleCategory function.

4. Under this function, we are querying the database with order as desc for the createdAt property and we only take the latest twelve product rows. We also select a specific property from the product that is required by the front end.

In this API, you will find that we have implemented pagination also. It helps us get more products under one category.

There are two kinds of pagination. One is cursor based, and another is offset-based pagination.

So why did we choose cursor-based pagination instead of offset-based pagination?

According to the Prisma docs,

"Offset pagination does not scale at a database level. For example, if you skip 200,00 records and take the first 10, the database still has to traverse the first 200,00 records before returning the 10 that you asked for - this negatively affects performance."

For more information read this helpful guide.

Update the URL in Postman to:

http://localhost:3000/api/categories/cl91683hp006d0mvlxlg5u176?cursorId=cl91685ht00b00mvllxjwzkqk

Our URL consists of two ids and you'll need to add cl91683hp006d0mvlxlg5u176 from the previous all-category response. This cl91685ht00b00mvllxjwzkqk id is just the cursor of the product and you can add this as the last one you want.

You'll get the following response:

Single Category Resp

Now let's create an API to get single product information.

Under the src/pages/api/products directory create a file named [title].ts and copy-paste the following code:

import type { NextApiRequest, NextApiResponse } from "next";
import nc from "next-connect";
import { prisma } from "../../../lib/prisma";
import { TApiErrorResp, TApiSingleProductResp } from "../../../types";

const getSingleProduct = async (
    req: NextApiRequest,
    res: NextApiResponse<TApiSingleProductResp | TApiErrorResp>
) => {
    try {
        const title = req.query.title as string;
        const product = await prisma.product.findUnique({
            where: {
                title,
            },
            select: {
                title: true,
                description: true,
                price: true,
                quantity: true,
                image: true,
            },
        });
        if (!product) {
            return res.status(404).json({ message: `Product not found` });
        }
        return res.status(200).json({ product });
    } catch (error) {
        return res.status(500).json({
            message: "Something went wrong!! Please try again after sometime",
        });
    }
};

const handler = nc({ attachParams: true }).get(getSingleProduct);

export default handler;

In the above snippet, we are doing the following:

1. By creating a file named [title].ts under src/pages/api/products we are informing NextJS to convert this to the /api/products/[title] API.

2. The [title] is the product title from the product table.

3. Using the next-connect library we are making sure that only the get operation is allowed for the getSingleProduct function.

4. Under this function, we are querying the database using the findUnique query based on the title.

Update the URL in Postman to:

http://localhost:3000/api/products/Practical Gorgeous Fresh Shoes

Here Practical Gorgeous Fresh Shoes is the title of the product we want to get. You can replace it with any product title from your database.

You'll get the following response:

Single Product Resp

How to Create the All Category and Single Category UIs:

Under src/pages/_app.tsx, replace the existing code with the following:

import { QueryClientProvider } from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
import type { AppProps } from "next/app";
import queryClient from "../lib/query";
import "../styles/globals.css";

function MyApp({ Component, pageProps }: AppProps) {
    return (
        <QueryClientProvider client={queryClient}>
            <ReactQueryDevtools initialIsOpen={false} />
            <Component {...pageProps} />
        </QueryClientProvider>
    );
}

export default MyApp;

Here we are wrapping all our components with React QueryClient Provider. But we also need to pass in the Client Context.

Under the src/lib directory create a new file named query.ts and copy-paste the following code:

import { QueryClient } from "@tanstack/react-query";

const queryClient = new QueryClient();

export default queryClient;

We are initiating a new QueryClient object and assigning it to the queryClient variable and exporting it as default. The reason we do this is that in this way we get to keep the queryClient object as a global context.

Under src/pages/index.tsx, replace the existing code with the following:

import { useQuery } from "@tanstack/react-query";
import type { NextPage } from "next";
import Head from "next/head";
import Navbar from "../components/Navbar";
import ProductGrid from "../components/ProductGrid";
import Skelton from "../components/Skelton";

const Home: NextPage = () => {
    const getAllCategories = async () => {
        try {
            const respJSON = await fetch("/api/categories");
            const resp = await respJSON.json();
            return resp;
        } catch (error) {
            throw error;
        }
    };

    const { isLoading, data } = useQuery(
        ["AllCategoreiesWithProducts"],
        getAllCategories
    );

    const categories = data?.categories;

    return (
        <div>
            <Head>
                <title>All Products</title>
                <meta name="description" content="All Products" />
                <link rel="icon" href="/favicon.ico" />
            </Head>

            <main className="container mx-auto">
                <Navbar />
                {isLoading ? (
                    <Skelton />
                ) : (
                    <>
                        {categories && categories?.length > 0 && (
                            <ProductGrid
                                showLink={true}
                                categories={categories}
                            />
                        )}
                    </>
                )}
            </main>
        </div>
    );
};

export default Home;

Let's understand our code.

Here we are fetching the data from the /api/categories endpoint that we wrote earlier. We are using useQuery to cache this data with the key AllCategoreiesWithProducts.

But there are three components that we haven't created yet. Let's create those and understand each one.

Under the src directory, create a components directory. Under the newly created components directory, create three files named Navbar.tsx, ProductGrid.tsx and Skelton.tsx.

Under Navbar.tsx copy-paste the following code:

import NextLink from "next/link";

const Navbar = () => {
    return (
        <div className="relative bg-white mx-6">
            <div className="flex items-center justify-between pt-6 md:justify-start md:space-x-10">
                <div className="flex justify-start lg:w-0 lg:flex-1">
                    <h1 className="text-2xl">
                        <NextLink href="/" className="cursor-pointer">
                            Ecomm App
                        </NextLink>
                    </h1>
                </div>
            </div>
        </div>
    );
};

export default Navbar;

Here we have created an h1 with the text as Ecomm App. We have wrapped this text around NextLink and set the location as /. So when user clicks on this, they will be redirected to the home page.

Under ProductGrid.tsx copy-paste the following code:

import NextImage from "next/image";
import NextLink from "next/link";
import { useEffect } from "react";
import { AiOutlineRight } from "react-icons/ai";
import { useInView } from "react-intersection-observer";
import { TApiAllCategoriesResp } from "../types";

interface IProductGrid extends TApiAllCategoriesResp {
    showLink: boolean;
    hasMore?: boolean;
    loadMoreFun?: Function;
}

const ProductGrid = (props: IProductGrid) => {
    const { categories, showLink, loadMoreFun, hasMore } = props;
    const { ref, inView } = useInView();

    useEffect(() => {
        if (inView) {
            if (loadMoreFun) loadMoreFun();
        }
    }, [inView, loadMoreFun]);

    return (
        <div className="bg-white">
            {categories.map((category) => (
                <div className="mt-12  p-6" key={category.name}>
                    <div className="flex flex-row justify-between">
                        <span className="inline-flex items-center rounded-md bg-sky-800 px-8 py-2 text-md font-medium text-white">
                            {category.name}
                        </span>
                        {showLink && (
                            <NextLink href={`/category/${category.id}`}>
                                <p className="flex flex-row gap-2 underline hover:cursor-pointer items-center">
                                    View More
                                    <AiOutlineRight />
                                </p>
                            </NextLink>
                        )}
                    </div>
                    <div className="mt-6  grid grid-cols-1 gap-y-10 gap-x-6 xl:gap-x-8 sm:grid-cols-2 lg:grid-cols-4">
                        {category?.products.map((product) => (
                            <div
                                className="p-6 group rounded-lg border border-gray-200 bg-neutral-200"
                                key={product.title}
                            >
                                <div className="min-h-80 w-full overflow-hidden rounded-md group-hover:opacity-75 lg:aspect-none lg:h-80">
                                    <NextImage
                                        priority={true}
                                        layout="responsive"
                                        width="25"
                                        height="25"
                                        src={`${product.image}`}
                                        alt={product.title}
                                        className="h-full w-full object-cover object-center lg:h-full lg:w-full"
                                    />
                                </div>
                                <div className="relative mt-2">
                                    <h3 className="text-sm font-medium text-gray-900">
                                        {product.title}
                                    </h3>
                                    <p className="mt-1 text-sm text-gray-500">
                                        {product.price}
                                    </p>
                                </div>
                                <div className="mt-6">
                                    <NextLink
                                        href={`/product/${product.title}`}
                                    >
                                        <p className="relative flex items-center justify-center rounded-md border border-transparent bg-sky-800 py-2 px-8 text-sm font-medium text-white hover:bg-sky-900 hover:cursor-pointer">
                                            View More Details
                                        </p>
                                    </NextLink>
                                </div>
                            </div>
                        ))}
                    </div>
                    {!showLink && (
                        <div className="flex items-center justify-center mt-8">
                            {hasMore ? (
                                <button
                                    ref={ref}
                                    type="button"
                                    className="inline-flex items-center rounded-md border border-transparent bg-sky-800 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-sky-900"
                                >
                                    Loading...
                                </button>
                            ) : (
                                <div className="border-l-4 border-yellow-400 bg-yellow-50 p-4 w-full">
                                    <div className="flex">
                                        <div className="ml-3">
                                            <p className="text-sm text-yellow-700">
                                                You have viewed all the Products
                                                under this category.
                                            </p>
                                        </div>
                                    </div>
                                </div>
                            )}
                        </div>
                    )}
                    {showLink && (
                        <div className="w-full border-b border-gray-300 mt-24" />
                    )}
                </div>
            ))}
        </div>
    );
};

export default ProductGrid;

Here we have created a grid that will show 1 column for the base screen. For the sm screen it will show 2 columns and for the lg screen it will show 4 columns.

Under this, we have a single card which has a Title, Price, and View More Details button. The View More Details button redirects the user to a single product page which will create a bit later.

Apart from that, we are using the useInView hook from the react-intersection-observer library to find the user's cursor on the screen. This ref is attached to a Loading... button and once user is near it then we execute the loadMoreFn function.

It makes an API call to the server to get the next twelve rows from the last cursor.

Under Skelton.tsx copy-paste the following code:

const Skelton = () => {
    return (
        <>
            <div className="mt-12 h-8 w-40 rounded-lg bg-gray-200" />
            <div className="mt-6 grid grid-cols-1 gap-y-10 gap-x-6 sm:grid-cols-2 lg:grid-cols-4 xl:gap-x-8">
                {Array(16)
                    .fill(0)
                    .map((_val, index) => (
                        <div className="rounded-2xl bg-black/5 p-4" key={index}>
                            <div className="h-60 rounded-lg bg-gray-200" />
                            <div className="space-y-4 mt-6 mb-4">
                                <div className="h-3 w-3/5 rounded-lg bg-gray-200" />
                                <div className="h-3 w-4/5 rounded-lg bg-gray-200" />
                            </div>
                        </div>
                    ))}
            </div>
        </>
    );
};

export default Skelton;

We are using placeimg to get fake images for our product and we are using the Next Image component which requires that it be mentioned under next.config.js.

Replace the existing code in next.config.js with the following code:

/** @type {import('next').NextConfig} */
const nextConfig = {
    reactStrictMode: true,
    swcMinify: true,
    images: {
        domains: ["placeimg.com"],
    },
};

module.exports = nextConfig

We will need to restart our server. Use the following command to start your development server again:

npm run dev

Open http://localhost:3000/ and you'll see the following UI:

All Products Page

Now let's create a single category page that the user can go to using a View More link.

Under src/pages create a directory named category. Under this directory create a file named [id].tsx and copy paste the following code:

import { useInfiniteQuery } from "@tanstack/react-query";
import Head from "next/head";
import { useRouter } from "next/router";
import Navbar from "../../components/Navbar";
import ProductGrid from "../../components/ProductGrid";
import Skelton from "../../components/Skelton";

const SingleCategory = () => {
    const router = useRouter();

    const getSingleCategory = async ({ pageParam = null }) => {
        try {
            let url = `/api/categories/${router.query.id}`;
            if (pageParam) {
                url += `?cursorId=${pageParam}`;
            }
            const respJSON = await fetch(url);
            const resp = await respJSON.json();
            return resp;
        } catch (error) {
            throw error;
        }
    };

    const { isLoading, data, fetchNextPage, isError } = useInfiniteQuery(
        [`singleCategory ${router.query.id as string}`],
        getSingleCategory,
        {
            enabled: !!router.query.id,
            getNextPageParam: (lastPage) => {
                const nextCursor =
                    lastPage?.category?.products[
                        lastPage?.category?.products?.length - 1
                    ]?.id;
                return nextCursor;
            },
        }
    );

    const allProductsWithCategory: any = {
        name: "",
        products: [],
        hasMore: true,
    };

    data?.pages.map((page) => {
        if (page?.category) {
            if (page.category?.name) {
                allProductsWithCategory.name = page.category?.name;
            }
            if (page.category?.products && page.category?.products.length > 0) {
                allProductsWithCategory.products.push(
                    ...page.category?.products
                );
            }
        }
        return page?.category;
    });

    if (data?.pages[data?.pages.length - 1]?.category?.products.length === 0) {
        allProductsWithCategory.hasMore = false;
    }

    return (
        <div>
            <Head>
                <title>
                    {isLoading
                        ? "Loading..."
                        : `All ${allProductsWithCategory?.name} Product`}
                </title>
                <meta
                    name="description"
                    content="Generated by create next app"
                />
                <link rel="icon" href="/favicon.ico" />
            </Head>
            <main className="container mx-auto">
                <Navbar />
                {isLoading ? (
                    <Skelton />
                ) : (
                    <>
                        {allProductsWithCategory &&
                            allProductsWithCategory.products.length > 0 && (
                                <ProductGrid
                                    hasMore={allProductsWithCategory.hasMore}
                                    showLink={false}
                                    categories={[allProductsWithCategory]}
                                    loadMoreFun={fetchNextPage}
                                />
                            )}
                    </>
                )}
            </main>
        </div>
    );
};

export default SingleCategory;

Here we are calling the /api/categories/[id] API to get the latest twelve products for that category id.

We are using the useInfiniteQuery hook from react query to fetch the data. This hook is useful for cursor-based pagination. We will be using the ProductGrid component that we created earlier.

Open http://localhost:3000/, click on the View More link for any of the category, and you'll see the following UI:

Single Category Page

The difference between the previous UI and the current is that we now don't have the View More Link in the top right corner. Also, when you scroll below, you'll get more products for that category.

Once we scroll through all the products in that category we will see the following warning alert:

How to Implement Single Product UI and Stripe Checkout.

In this section, we'll implement the following functionality:

1. Create Single Product UI

2. Create Stripe Checkout

You can find the eCommerce website code implemented in this section at this commit.

How to Create the Single Product UI:

Under the src/pages directory create a directory named product.

Under this directory create a file named [title].tsx and copy-paste the following code:

import { loadStripe, Stripe } from "@stripe/stripe-js";
import { useMutation, useQuery } from "@tanstack/react-query";
import Head from "next/head";
import NextImage from "next/image";
import { useRouter } from "next/router";
import Navbar from "../../components/Navbar";
import Skelton from "../../components/Skelton";

const stripePromiseclientSide = loadStripe(
    process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
);

const SingleProduct = () => {
    const router = useRouter();

    const getSingleProduct = async () => {
        try {
            const title = router?.query?.title;

            const respJSON = await fetch(`/api/products/${title}`);
            const resp = await respJSON.json();
            return resp;
        } catch (error) {
            throw error;
        }
    };

    const { mutate, isLoading: mutationIsLoading } = useMutation(
        async (body: any) => {
            try {
                const respJSON = await fetch("/api/create-checkout-session", {
                    method: "POST",
                    body: JSON.stringify(body),
                });
                const resp = await respJSON.json();
                const stripe = (await stripePromiseclientSide) as Stripe;
                const result = await stripe.redirectToCheckout({
                    sessionId: resp.id,
                });
                return result;
            } catch (error) {
                throw error;
            }
        }
    );

    const { data, isLoading } = useQuery(
        [`singleProduct, ${router?.query?.title}`],
        getSingleProduct,
        {
            enabled: !!router?.query?.title,
        }
    );

    const product = data?.product;

    return (
        <div>
            <Head>
                <title>{isLoading ? "Loading..." : `${product?.title}`}</title>
                <meta
                    name="description"
                    content="Generated by create next app"
                />
                <link rel="icon" href="/favicon.ico" />
            </Head>
            <main className="container mx-6 md:mx-auto">
                <Navbar />
                {isLoading ? (
                    <Skelton />
                ) : (
                    <div className="bg-white">
                        <div className="pt-6 pb-16 sm:pb-24">
                            <div className="mx-auto mt-8">
                                <div className="flex flex-col md:flex-row gap-x-8">
                                    <div className="min-h-80 w-full overflow-hidden rounded-md group-hover:opacity-75 lg:aspect-none lg:h-80">
                                        <NextImage
                                            layout="responsive"
                                            width="25"
                                            height="25"
                                            src={`${product.image}`}
                                            alt={product.title}
                                            className="h-full w-full object-cover object-center lg:h-full lg:w-full"
                                        />
                                    </div>
                                    <div className="lg:col-span-5 lg:col-start-8 mt-8 md:mt-0">
                                        <h1 className="text-xl font-medium text-gray-900 ">
                                            {product.title}
                                        </h1>
                                        <p className="text-xl font-light text-gray-700 mt-4">
                                            {product.description}
                                        </p>
                                        <p className="text-xl font-normal text-gray-500 mt-4">
                                            USD {product.price}
                                        </p>
                                        <button
                                            onClick={() =>
                                                mutate({
                                                    title: product.title,
                                                    image: product.image,
                                                    description:
                                                        product.description,
                                                    price: product.price,
                                                })
                                            }
                                            disabled={mutationIsLoading}
                                            type="button"
                                            className="inline-flex items-center rounded-md border border-transparent bg-sky-800 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-sky-900  mt-4"
                                        >
                                            Buy Now
                                        </button>
                                    </div>
                                </div>
                            </div>
                        </div>
                    </div>
                )}
            </main>
        </div>
    );
};

export default SingleProduct;

Here we are calling /api/products/title API to get the latest product. We have also created Stripe Interface for creating a checkout method once a user clicks the Buy Now button.

Once the user clicks the Buy Now button, we make an API call to /api/create-checkout-session using the useMutation hook. On a successful response, we redirect the user to the Stripe default checkout page.

Open http://localhost:3000/ and click on View More Details button for any product.

You'll see the following UI:

Single Product Page

You can also visit this page by clicking on the View More link and then clicking on the View More Details button for any product.

How to Set Up Stripe Checkout:

To set up Stripe Checkout, we need to add a new file under the lib directory.

Create a new file named stripe.ts under the lib directory and copy paste the following code:

import Stripe from "stripe";

const stripeServerSide = new Stripe(process.env.STRIPE_SECRET_KEY!, {
    apiVersion: "2022-08-01",
});

export { stripeServerSide };

Here we are creating server-side instances of Stripe. Now under the pages/api directory, create a new file named create-checkout-session.ts and copy-paste the following code:

import currency from "currency.js";
import type { NextApiRequest, NextApiResponse } from "next";
import nc from "next-connect";
import { stripeServerSide } from "../../lib/stripe";
import { TApiErrorResp } from "../../types";

const checkoutSession = async (
    req: NextApiRequest,
    res: NextApiResponse<any | TApiErrorResp>
) => {
    try {
        const host = req.headers.origin;
        const referer = req.headers.referer;
        const body = JSON.parse(req.body);
        const formatedPrice = currency(body.price, {
            precision: 2,
            symbol: "",
        }).multiply(100);
        const session = await stripeServerSide.checkout.sessions.create({
            mode: "payment",
            payment_method_types: ["card"],
            line_items: [
                {
                    price_data: {
                        currency: "usd",
                        product_data: {
                            name: body?.title,
                            images: [body.image],
                            description: body?.description,
                        },
                        unit_amount_decimal: formatedPrice.toString(),
                    },
                    quantity: 1,
                },
            ],
            success_url: `${host}/thank-you`,
            cancel_url: `${referer}?status=cancel`,
        });
        return res.status(200).json({ id: session.id });
    } catch (error) {
        return res.status(500).json({
            message: "Something went wrong!! Please try again after sometime",
        });
    }
};

const handler = nc({ attachParams: true }).post(checkoutSession);

export default handler;

In the snippet above we are doing the following:

1. Formatting the price with precision as two and multiplying it by 100 as Stripe expects the unit_amount in cents by default.

2. We create the session and pass the id as the response.

Now we need to create another page named thank-you.tsx under the src/pages directory. Once the product purchase is successful, Stripe Checkout will redirect to this page.

Copy-paste the following code under this file:

import Head from "next/head";
import { useRouter } from "next/router";
import { HiCheckCircle } from "react-icons/hi";
import Navbar from "../components/Navbar";

const ThankYou = () => {
    const router = useRouter();
    return (
        <div>
            <Head>
                <title>Thank You</title>
                <meta name="description" content="All Products" />
                <link rel="icon" href="/favicon.ico" />
            </Head>

            <main className="container mx-auto">
                <Navbar />
                <div className="rounded-md bg-green-50 p-4 mt-8">
                    <div className="flex">
                        <div className="flex-shrink-0">
                            <HiCheckCircle
                                className="h-5 w-5 text-green-400"
                                aria-hidden="true"
                            />
                        </div>
                        <div className="ml-3">
                            <h3 className="text-sm font-medium text-green-800">
                                Order Placed
                            </h3>
                            <div className="mt-2 text-sm text-green-700">
                                <p>
                                    Thank you for your Order. We have placed the
                                    order and your email will recieve further
                                    details.
                                </p>
                            </div>
                            <button
                                onClick={() => router.push("/")}
                                type="button"
                                className="inline-flex items-center rounded-md border border-transparent bg-sky-800 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-sky-900 mt-4"
                            >
                                Continue Shopping
                            </button>
                        </div>
                    </div>
                </div>
            </main>
        </div>
    );
};

export default ThankYou;

Open http://localhost:3000/ and click on the View More Details button of any product.

Click on the Buy Now button and you'll be redirected to the following page:

Add all the details for the test card. You can use any card from this link. Stripe provides various test cards which work only during Test Mode. Once you click on Pay and payment processing happens, Stripe will redirect you to the success page.

Thank You Page

How to Deploy the Website to Production

In this section, we'll implement the following functionality:

1. Promote our PlanetScale branch to Main.

2. Deploy the app on Vercel.

How to Promote the PlanetScale Branch to Main:

To promote the branch to main, we can do it either via the terminal or dashboard. I'll use the dashboard for this tutorial.

Go to your project on PlanetScale and you'll find the following message on the dashboard:

PlanetScale Database Promotion

Let's click on the Promote a branch to production button and you'll get a confirmation model. Click on the Promote branch button. Once done you'll get a toast with a success message.

How to Deploy to Vercel:

If you don't have an account on Vercel, you can create one here.

You can create a project on GitHub and push it to the Main branch. If you don't know how, you can check out this tutorial.

Once the project is pushed on GitHub, go to Vercel and create an Add New button and select Project from the drop down.

Add New Project Vercel

You'll get the following the UI:

Select Git Provider Vercel

As we have pushed the code on GitHub, let's click on the Continue with GitHub button. You'll get the following UI:

Select Git Repository Vercel

Click on Import and you'll get the following UI:

Configure Project Vercel

Click on the Environment Variables and add these three there:

Add NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY, and DATABASE_URL

Once done click the Deploy button. You'll get the following UI once the deployment starts:

Deploying Vercel

Once deployed, Vercel will give you a Unique URL.

Visit this URL and you'll find its failing. Let's go to the deployment > functions and you'll see the following error:

Prisma generate Fails

We need to update our build command in package.json as follows:

"build": "npx prisma generate && next build",

Push the code again to the Git repository and you'll find that Vercel starts redeploying your project.

Once the deployment is done, you can visit your application URL and you'll find it shows all your products.

With this, we have created our production-ready eCommerce application. If you have built the website along with the tutorial, then a very big congratulations to you on this achievement.

Thank you for reading!

Feel free to connect with me on Twitter and Github.

If you want any project to be developed or want to consult with me, you can DM me on my Twitter (@sharvinshah26 ).

Have you ever woken up in the middle of the night, worried that you are not using the Stripe npm module properly? Probably not, but this article will help put your troubled soul at ease anyway with some interactive Node.js examples that explain how to build an excellent Stripe integration.

1. Use auto-pagination to avoid bloated code

Pagination is a necessary evil that saves us from loading too much data, but dealing with it in code can be a pain. Before v6.11.0, your Stripe code would look something like this to deal with pagination:

This example shows the old way of handling pagination in Stripe

//require Stripe's Node bindings
const stripe = require("stripe")("rk_test_72wdhn7pifTOWbrtrSNFxhsQ00NrdzPvaC")

//get first 100 invoices
let invoices = await stripe.invoices.list({limit: 100});
let numberProcessed = 0;

//loop through these invoices
for(let invoice of invoices.data){
    numberProcessed++;
}

//has_more indicates if we need to deal with pagination
while(invoices.has_more){

    //starting_after will be the the id of the last result
    invoices = await stripe.invoices.list({limit: 100, starting_after: invoices.data[invoices.data.length -1].id});

    //loop through the next 100
    for(let invoice of invoices.data){
        numberProcessed++;
    }
    console.log("Number processed so far: " + numberProcessed);
}
console.log("Total Number Processed: " + numberProcessed);

With the introduction of auto-pagination in v6.11.0, we are now able to have a much more efficient way of paginating:

This example shows how to auto-paginate in Stripe

//require Stripe's Node bindings
const stripe = require("stripe")("rk_test_72wdhn7pifTOWbrtrSNFxhsQ00NrdzPvaC")

//get all invoices
const allInvoices = await stripe.invoices.list({limit: 100}).autoPagingToArray({limit: 10000});
console.log("Invoices - " + allInvoices.length);

Note: You need to be running Node.js v10 or above for this.

2. Use expand to reduce the number of API calls

In Stripe, there are a lot of different objects. A lot of times, when dealing with one type of object, say a subscription; you want to get the product that subscription belongs. To get the product, you need to make an extra call to Stripe as shown here:

This example shows how to get the product from a subscription in Stripe without using expand

//require Stripe's Node bindings
const stripe = require("stripe")("rk_test_3U9s3aPLquPOczvc4FVRQKdo00AhMZlMIE")

const subscription = await stripe.subscriptions.retrieve("sub_G0zK9485afDl6O");
const product = await stripe.products.retrieve(subscription.plan.product);
console.log(product.name);

We can effectively avoid this by using the "expand" attribute in Stripe's API:

This example shows getting the product by using expand

//require Stripe's Node bindings
const stripe = require("stripe")("rk_test_3U9s3aPLquPOczvc4FVRQKdo00AhMZlMIE")

//expand the product inside the plan
const subscription = await stripe.subscriptions.retrieve("sub_G0zK9485afDl6O", {expand: "plan.product"});
console.log(subscription.plan.product.name);

Cutting down on API calls will improve your app's performance and reduce the risk of hitting Stripe's API limits.

3. Configure your Stripe connection for a more stable experience

Most people with a simple Stripe integration will define a new Stripe connection on the fly without configuring it first like so:

const stripe = require("stripe")("STRIPE_SECRET_KEY");

When scaling your billing system, consider doing the following to improve your integration quality:

• Lock your API version to avoid being affected by API changes
• Set to Retry Automatically in case of network failure
• Define your app information to help the Stripe team

Here's an example function that returns a configured Stripe connection

function createStripeConnection(stripe_api_key){
    const Stripe = require("stripe");
    const stripe = Stripe(stripe_api_key);
    stripe.setApiVersion('2019-03-14');//lock API version down to avoid code breaking
    stripe.setAppInfo({
        name: 'Servicebot',
        version: "1.1.3", //Optional
        url: 'https://servicebot.io' // Optional
    });
    stripe.setMaxNetworkRetries(3); //retry on network failure
    return stripe;
}

const stripe = createStripeConnection("rk_test_72wdhn7pifTOWbrtrSNFxhsQ00NrdzPvaC");
console.log(await stripe.invoices.list());

4. Use Webhooks to process events that occur in Stripe

Webhooks play an essential role in most Stripe integrations. There are a lot of different events that happen, so which ones should you care about?

The most important webhook as a SaaS app to pay attention to is the customer.subscription.deleted - when a subscription goes into state cancelled. You listen for this event in order to decide what to do with someone's account when they cancel, trial runs out, or their card fails.

Once you start listening to Stripe events, it is a good idea to secure your webhook receiver as not to be fed phony webhooks by a bad-actor. You do this by utilizing Stripe's webhook si gning functionality:

This example shows how to validate a webhook has come from Stripe

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_bkoS59kZFWBR3XZgkiHwozoX00lD4ttSs1');

// Find your endpoint's secret in your Dashboard's webhook settings
const endpointSecret = 'whsec_...';

// This example uses Express to receive webhooks
const app = require('express')();

// Use body-parser to retrieve the raw body as a buffer
const bodyParser = require('body-parser');

// Match the raw body to content type application/json
app.post('/webhook', bodyParser.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['stripe-signature'];

  let event;

  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  }
  catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      handlePaymentIntentSucceeded(paymentIntent);
      break;
    case 'payment_method.attached':
      const paymentMethod = event.data.object;
      handlePaymentMethodAttached(paymentMethod);
      break;
    // ... handle other event types
    default:
      // Unexpected event type
      return response.status(400).end();
  }

  // Return a response to acknowledge receipt of the event
  response.json({received: true});
});

app.listen(8000, () => console.log('Running on port 8000'));

Avoid the effort of building and maintaining a complex Stripe Integration

Your billing code can get pretty complicated when it comes to having a fully-featured solution that includes coupons, free trials, metered billing, and more.

Building a user interface for your Stripe integration could take months to develop. Servicebot provides a drop-in UI for Stripe Billing. It takes less than an hour to set up and doesn’t require any development effort.

What are PSD2, SCA, and 3DS?

PSD2

The second Payment Services Directive (PSD2) is an EU directive announced in 2015. The goal of PSD2 is to protect people when they pay online, promote open banking, and make cross-border European payment services safer. It went into effect September of 2019.

SCA

Strong Customer Authentication (SCA) is a requirement of the PSD2 that ensures online payments are performed with multi-factor authentication to increase the security of online payments. Even though PSD2 was enacted in September of 2019, SCA has been delayed by 18 months to allow merchants and banks more time to implement solutions.

3DS2

3-D Secure 2.0 (3DS2) is the second iteration of the 3DS, used to power brand-name systems such as Visa Secure, Mastercard Identity Check, and American Express SafeKey. It was designed to reduce fraud and provide added security to online payments and supported by many major banks.

3DS2 is considered an SCA compliant solution. If your business implements 3DS2, you will no longer be in danger of having your charges declined by banks.

Does SCA affect your SaaS business?

SCA is considered in-effect on all e-commerce payments when both:

• The business is in the EU
• The customer's bank is in the EU

If SCA applies to you and you do not authenticate your customer's transactions you risk having charges declined by banks.

There are exemptions for several types of transactions defined in Articles 12-18 of the PSD2. As a SaaS company, the most critical exception to note is Article 13. This article states that recurring transactions do not need to be subject to SCA. What this means is that you only need to have an SCA implementation to handle the initial creation of a subscription and not the subsequent recurring charges.

If you are interested in reading a breakdown of the other exemptions and how they may apply to you, Stripe goes into depth on each here.

Should you be SCA-ready even if you aren't in Europe?

There are benefits to implementing a solution such as 3DS2, even if you aren't affected by PSD2 or SCA. By implementing 3DS2, you will handle customer information in a much more secure manner, as well as shifting liability from you to the card issuer, reducing the risk of chargebacks.

How do you become SCA compliant?

Being SCA compliant as a SaaS means that all online payments are authorized using two of the three elements,

As I mentioned before, 3DS2 is an SCA-compliant solution. Drop-in solutions such as Servicebot, PayPal, and Stripe Checkout already use 3DS2 and are therefore SCA-compliant. If you are using a custom-built solution using something like Stripe Billing or Braintree to manage your subscriptions, you will need to develop a 3DS2 implementation.

How do you implement 3DS2 using Stripe Billing?

Stripe has created two new objects as part of offering an SCA-compliant solution, PaymentIntent and SetupIntent, to facilitate using 3DS2. A PaymentIntent represents the intent to charge someone and is used as part of a payment authentication flow. SetupIntents are similar to PaymentIntents, but they represent the intent to charge someone's card eventually. You will use SetupIntents if your SaaS has a free trial, or offers a free tier, essentially anywhere a credit card will be charged at a later date.

Using PaymentIntents

If you are using Stripe Billing to create subscriptions, you are already using PaymentIntents by default. They are created and attached to each invoice for every new subscription. If you want to know if a new subscription requires SCA, you can check the status of the payment_intent on the latest_invoice of the subscription. The object will contain a status of requires_action - Run the following NodeJS code to see it in action.

This code creates a subscription that requires SCA

const STRIPE_TEST_SECRET_KEY = "rk_test_3U9s3aPLquPOczvc4FVRQKdo00AhMZlMIE";
let stripe = require("stripe")(STRIPE_TEST_SECRET_KEY);
const sub = await stripe.subscriptions.create({ //creates a SCA-required subscription
    items: [{plan : "plan_FvnU01xoIPrg9l"}], //$300 per month plan without free trial
    customer: "cus_G0juGVZSLskx57",
    default_payment_method: "pm_1FUiR8CISNxwKLmI8uIQDdnv", //This PaymentMethod always requires SCA
    expand: ["latest_invoice.payment_intent"] //we expand the payload to show up the payment intent
});
const paymentIntent = sub.latest_invoice.payment_intent;
console.log(`Subscription Status: ${sub.status}`);
console.log(`PaymentIntent Status: ${paymentIntent.status}`)
console.log(paymentIntent.status === "requires_action" ? "SCA Required" : "No SCA Required");
console.log(sub);

Once you know you have a subscription that requires authentication, you can use the PaymentIntent's client_secret on the browser to start a 3DS2 Authentication process using Stripe.js

Using Stripe.js handleCardPayment with the PaymentIntent

Stripe.js has a handy function called handleCardPayment, which takes in a client secret from a payment intent and starts the 3DS2 process to authenticate the payment.

await stripe.handleCardPayment('PAYMENTINTENT_SECRET');

You can see this in action here

Once the customer authenticates, the subscription will move from an incomplete state to an active one, and the customer will be billed successfully.

SetupIntents

As a SaaS business, you will mostly be interacting with SetupIntents if you are either using a Free-tier or give a Free trial. When someone enters a credit card, for one of these subscriptions, you will see a pending_setup_intent on the subscription object. The SetupIntent's client_secret should be passed to the front-end so that Stripe.js can start the 3DS2 authentication flow.

Using Stripe.js handleCardSetup with the SetupIntent

This is basically identical to how we handled the PaymentIntent, except we call handleCardSetup instead

await stripe.handleCardSetup('{SETUP_INTENT_CLIENT_SECRET}')

You can see a SetupIntent SCA Flow in action below.

Once authentication completes, the customer can be moved to a paid plan later or have their card charged after a free trial is over.

No-code alternative

If you are looking for an SCA-compliant solution for Stripe Billing without having to deal with the 3DS2 integration development, check out Servicebot. We provide a drop-in UI for SaaS companies using Stripe, which is SCA-compliant out-of-the-box! Want to see it in action? Check out this demo and use the test card 4000002760003184 (any Expiration and CVC).