Next.js Minimal Boilerplate

Overview

The Next.js minimal boilerplate is a starter app with Dodo Payments already connected. Add your API keys and product IDs, and you get a pricing page that opens checkout, a webhook endpoint for payment events, and a link to the Customer Portal.

This boilerplate uses the Next.js 16 App Router with TypeScript, Tailwind CSS 4, and the @dodopayments/nextjs adaptor. To add the same route handlers to an existing app, see the Next.js Adaptor.

Features

The boilerplate includes:

Quick Setup: Go from clone to a running pricing page in about five minutes.
Checkout: A pre-configured checkout flow built on @dodopayments/nextjs.
Pricing Page: A dark-themed pricing page styled with Tailwind CSS.
Webhook Handler: An endpoint that verifies each webhook signature and runs your code for the event.
Customer Portal: A header link that opens the Customer Portal, where customers manage their subscriptions.
TypeScript: Typed product definitions and handlers.
Pre-filled Checkout: Passes the customer’s name and email to checkout, so the customer doesn’t retype them.

Prerequisites

Before you begin, you need:

Node.js 20.9 or later, which Next.js 16 requires.
A Dodo Payments account, to create an API key and a webhook signing secret in the dashboard.

Quick Start

Clone the Repository

git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate

Install Dependencies

npm install

Get API Credentials

API Key: Create a key under Dashboard → Developer → API Keys.
Webhook Key: Add an endpoint under Dashboard → Developer → Webhooks, then copy its signing secret. The endpoint URL must be public and use HTTPS. To receive events on your machine, see Webhook Events.

Create both while the Live Mode switch in the sidebar is off. A test mode key works only with DODO_PAYMENTS_ENVIRONMENT=test_mode, and test mode payments don’t move real money.

Configure Environment Variables

Copy the example file to create a .env file in the root directory:

cp .env.example .env

Set the values to your Dodo Payments credentials:

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:3000
DODO_PAYMENTS_ENVIRONMENT=test_mode

The route handlers read these variables:

DODO_PAYMENTS_API_KEY authenticates the checkout and Customer Portal handlers.
DODO_PAYMENTS_WEBHOOK_KEY verifies webhook signatures.
DODO_PAYMENTS_RETURN_URL is where checkout sends the customer after payment.
DODO_PAYMENTS_ENVIRONMENT is test_mode or live_mode.

Don’t commit your .env file to version control. The repository’s .gitignore already excludes it.

Add Your Products

Replace the sample products in src/lib/products.ts with your own. Set each product_id to the ID of a product under Products in your dashboard:

export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];

The pricing page displays name, description, price, and features from this file. Checkout charges the price set on the product in Dodo Payments, so keep price in sync with it.

Run the Development Server

npm run dev

Open http://localhost:3000 to see your pricing page.

Project Structure

The checkout, Customer Portal, and webhook route handlers live under src/app/api/:

src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions

Customization

Update Product Information

Edit src/lib/products.ts to change:

Product IDs, from Products in your Dodo Payments dashboard
Prices
Features
Descriptions

Pre-fill Customer Data

src/app/components/ProductCard.tsx sends a hardcoded name and email with each checkout request. Replace them with the signed-in user’s details:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

Update Customer Portal

The Customer Portal link in src/app/components/Header.tsx opens /api/customer-portal with a hardcoded customer ID. Replace it with the signed-in user’s Dodo Payments customer ID:

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

To get a customer ID for testing, complete a test purchase, then copy the customer’s ID from Customers in the dashboard. In production, fetch the ID from your backend.

Webhook Events

The handler in src/app/api/webhook/route.ts verifies each request with DODO_PAYMENTS_WEBHOOK_KEY, then handles two events:

onSubscriptionActive runs when a subscription becomes active (subscription.active).
onPaymentSucceeded runs when a payment succeeds (payment.succeeded).

Add your business logic inside these handlers:

onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},

To handle more events, add their handlers, such as onSubscriptionCancelled. The Next.js Adaptor lists every supported handler. Dodo Payments can’t reach localhost. For local development, use a tunnel such as ngrok to expose your local server, and use the tunnel URL as your webhook endpoint.

Deployment

Build for Production

npm run build
npm start

Deploy to Vercel

Add the four environment variables in the Vercel dashboard, and set DODO_PAYMENTS_RETURN_URL to your production URL.

Update Webhook URL

After deploying, add your production webhook URL in the Dodo Payments Dashboard, with your domain in place of example.com:

https://example.com/api/webhook

Each endpoint has its own signing secret. Copy the new endpoint’s secret into DODO_PAYMENTS_WEBHOOK_KEY in your production environment.

Troubleshooting

Module not found or build errors

Delete node_modules and package-lock.json, then reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Check for these common causes:

The product ID doesn’t exist in your Dodo Payments dashboard.
The API key or DODO_PAYMENTS_ENVIRONMENT in .env is wrong. A test mode key works only with test_mode.

Look for the error in the browser console and in the terminal that runs npm run dev.

Webhooks not receiving events

For local testing, use ngrok to expose your server:

ngrok http 3000

In your Dodo dashboard, add an endpoint with the ngrok HTTPS URL followed by /api/webhook. Copy that endpoint’s signing secret into DODO_PAYMENTS_WEBHOOK_KEY in your .env file.

Customer portal link doesn't work

Replace the hardcoded CUSTOMER_ID in src/app/components/Header.tsx with the ID of a customer in your Dodo Payments dashboard.In production, get the customer ID from your authentication system and database instead.

Learn More

Dodo Payments Documentation
Checkout Sessions Documentation
Webhooks Documentation
Next.js Adaptor: options for the Checkout, CustomerPortal, and Webhooks handlers

Support

For help with the boilerplate:

Ask questions in the Discord community.
Report issues and follow updates in the GitHub repository.
Email the support team.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Overview

Features

Prerequisites

Quick Start

Project Structure

Customization

Update Product Information

Pre-fill Customer Data

Update Customer Portal

Webhook Events

Deployment

Build for Production

Deploy to Vercel

Update Webhook URL

Troubleshooting

Learn More

Support

​Overview

​Features

​Prerequisites

​Quick Start

​Project Structure

​Customization

​Update Product Information

​Pre-fill Customer Data

​Update Customer Portal

​Webhook Events

​Deployment

​Build for Production

​Deploy to Vercel

​Update Webhook URL

​Troubleshooting

​Learn More

​Support

Overview

Features

Prerequisites

Quick Start

Project Structure

Customization

Update Product Information

Pre-fill Customer Data

Update Customer Portal

Webhook Events

Deployment

Build for Production

Deploy to Vercel

Update Webhook URL

Troubleshooting

Learn More

Support