Next.js Minimal Boilerplate - Dodo Payments Documentation

Overview

The Next.js minimal boilerplate provides a ready-to-use starting point for integrating Dodo Payments with your Next.js application. This template includes checkout sessions, webhook handling, customer portal, and modern UI components to help you start accepting payments quickly.

This boilerplate uses Next.js 16 App Router with TypeScript, Tailwind CSS 4, and the @dodopayments/nextjs adapter.

Features

Quick Setup - Get started in under 5 minutes
Payment Integration - Pre-configured checkout flow using @dodopayments/nextjs
Modern UI - Clean, dark-themed pricing page with Tailwind CSS
Webhook Handler - Ready-to-use webhook endpoint for payment events
Customer Portal - One-click subscription management
TypeScript - Fully typed with minimal, focused types
Pre-filled Checkout - Demonstrates passing customer data to improve UX

Prerequisites

Before you begin, make sure you have:

Node.js 20.9+ (required for Next.js 16)
Dodo Payments account (to access API and Webhook Keys from 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: Dashboard → Developer → API Keys
Webhook Key: Dashboard → Developer → Webhooks

Make sure you’re in Test Mode while developing!

Configure Environment Variables

Create a .env file in the root directory:

cp .env.example .env

Update the values with 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

Never commit your .env file to version control. It’s already included in .gitignore.

Add Your Products

Update src/lib/products.ts with your actual product IDs from Dodo Payments:

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
];

Run the Development Server

npm run dev

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

Project Structure

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 modify:

Product IDs (from your Dodo dashboard)
Pricing
Features
Descriptions

Pre-fill Customer Data

In src/app/components/ProductCard.tsx, replace the hardcoded values with your actual user data:

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

Update Customer Portal

In src/app/components/Header.tsx, replace the hardcoded customer ID:

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

You can complete a test purchase to get the customer ID for testing.

Webhook Events

The boilerplate demonstrates handling two webhook events in src/app/api/webhook/route.ts:

onSubscriptionActive - Triggered when a subscription becomes active
onPaymentSucceeded - Triggered when a payment is successful

Add your business logic inside these handlers:

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

Add more webhook events as needed. For local development, you can use tools like ngrok to create a secure tunnel to your local server and use it as your webhook URL.

Deployment

Build for Production

npm run build
npm start

Deploy to Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Don’t forget to add your environment variables in the Vercel dashboard!

Update Webhook URL

After deploying, update your webhook URL in the Dodo Payments Dashboard:

https://example.com/api/webhook

Troubleshooting

Module not found or build errors

Delete node_modules and reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Common causes:

Invalid product ID - verify it exists in your Dodo dashboard
Wrong API key or environment setting in .env
Check browser console and terminal for errors

Webhooks not receiving events

For local testing, use ngrok to expose your server:

ngrok http 3000

Update the webhook URL in your Dodo dashboard to the ngrok URL. Remember to update your .env file with the correct webhook verification key.

Customer portal link doesn't work

Replace the hardcoded CUSTOMER_ID in src/app/components/Header.tsx with an actual customer ID from your Dodo dashboard.Or integrate your authentication system and database to fetch the customer ID dynamically.

Learn More

Support

Need help with the boilerplate?

Join our Discord community for questions and discussions
Check the GitHub repository for issues and updates
Contact our support team for assistance

​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