> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js Minimal Boilerplate

> Get started quickly with our minimal Next.js boilerplate for integrating Dodo Payments into your Next.js application

## 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.

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

### 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

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
    cd dodo-nextjs-minimal-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Get API Credentials">
    Sign up at [Dodo Payments](https://dodopayments.com/) and get your credentials from the dashboard:

    * **API Key:** [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Make sure you're in **Test Mode** while developing!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in the root directory:

    ```bash theme={null}
    cp .env.example .env
    ```

    Update the values with your Dodo Payments credentials:

    ```env theme={null}
    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
    ```

    <Warning>
      Never commit your `.env` file to version control. It's already included in `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Update `src/lib/products.ts` with your actual product IDs from Dodo Payments:

    ```typescript theme={null}
    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
    ];
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    npm run dev
    ```

    Open [http://localhost:3000](http://localhost:3000) to see your pricing page!
  </Step>
</Steps>

## Project Structure

```text theme={null}
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:

```typescript theme={null}
customer: {
  name: "John Doe",
  email: "john@example.com",
},
```

### Update Customer Portal

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

```typescript theme={null}
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:

```typescript theme={null}
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](https://ngrok.com/) to create a secure tunnel to your local server and use it as your webhook URL.

## Deployment

### Build for Production

```bash theme={null}
npm run build
npm start
```

### Deploy to Vercel

[![Deploy with Vercel](https://vercel.com/button)](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://app.dodopayments.com/developer/webhooks):

```
https://example.com/api/webhook
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Delete `node_modules` and reinstall dependencies:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    For local testing, use [ngrok](https://ngrok.com) to expose your server:

    ```bash theme={null}
    ngrok http 3000
    ```

    Update the webhook URL in your [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) to the ngrok URL. Remember to update your .env file with the correct webhook verification key.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Learn More

* [Dodo Payments Documentation](https://docs.dodopayments.com/)
* [Checkout Sessions Documentation](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Webhooks Documentation](https://docs.dodopayments.com/developer-resources/webhooks)

## Support

Need help with the boilerplate?

* Join our [Discord community](https://discord.gg/bYqAp4ayYh) for questions and discussions
* Check the [GitHub repository](https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) for issues and updates
* Contact our [support team](mailto:support@dodopayments.com) for assistance