Astro Minimal Boilerplate

Overview

The Astro 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 Astro 5 with TypeScript, Tailwind CSS 4, and the @dodopayments/astro adaptor. To add the same API routes to an existing app, see the Astro 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/astro.
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:

A Node.js LTS version, which Astro 5 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-astro-minimal-boilerplate.git
cd dodo-astro-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:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode

.env.example sets DODO_PAYMENTS_RETURN_URL to port 3000. Change it to 4321, the port the Astro dev server uses, so that checkout returns the customer to your app.The API routes read these variables:

DODO_PAYMENTS_API_KEY authenticates the checkout and Customer Portal routes.
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:4321 to see your pricing page.

Project Structure

The checkout, Customer Portal, and webhook API routes live under src/pages/api/:

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

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

The checkout script in src/components/ProductCard.astro 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/components/Header.astro opens /api/customer-portal with a hardcoded customer ID. Replace it with the customer ID from your authentication system or database:

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.

Webhook Events

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

onSubscriptionActive runs when a subscription becomes active (subscription.active).
onSubscriptionCancelled runs when a subscription is cancelled (subscription.cancelled).

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 onPaymentSucceeded. The Astro 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

Astro builds the pages as static output, and each API route sets export const prerender = false so that it renders on demand. On-demand routes need an Astro adapter for your deployment platform:

Platform	Guide
Vercel	Deploy to Vercel
Netlify	Deploy to Netlify
Cloudflare	Deploy to Cloudflare

For other platforms, see Astro’s deployment guides. In your hosting platform, add the four environment variables 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:

https://your-domain.com/api/webhook

Each endpoint has its own signing secret. Set DODO_PAYMENTS_WEBHOOK_KEY in your production environment to the signing secret of this endpoint.

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 4321

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/components/Header.astro with the ID of a customer in your Dodo Payments dashboard.In production, get the customer ID from your authentication system and database instead.

Build fails with adapter error

The API routes render on demand, and the repository doesn’t include a deployment adapter. Install the Astro adapter for your platform before you build for production.See Astro’s deployment guides for details.

Learn More

Dodo Payments Documentation
Checkout Sessions Documentation
Webhooks Documentation
Astro Adaptor: options for the Checkout, CustomerPortal, and Webhooks handlers
Astro Documentation

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

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

​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

Update Webhook URL

Troubleshooting

Learn More

Support