Skip to main content

​
Overview

The Astro minimal boilerplate provides a ready-to-use starting point for integrating Dodo Payments with your Astro application. This template includes checkout sessions, webhook handling, customer portal, and modern UI components to help you start accepting payments quickly.
This boilerplate uses Astro 5 with TypeScript, Tailwind CSS 4, and the @dodopayments/astro adapter.

​
Features

  • Quick Setup - Get started in under 5 minutes
  • Payment Integration - Pre-configured checkout flow using @dodopayments/astro
  • 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 LTS version (required for Astro 5)
  • Dodo Payments account (to access API and Webhook Keys from dashboard)

​
Quick Start

1

Clone the Repository

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

Install Dependencies

npm install
3

Get API Credentials

Sign up at Dodo Payments and get your credentials from the dashboard:
Make sure you’re in Test Mode while developing!
4

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:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode
Never commit your .env file to version control. It’s already included in .gitignore.
5

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

Run the Development Server

npm run dev
Open http://localhost:4321 to see your pricing page!

​
Project Structure

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 modify:
  • Product IDs (from your Dodo dashboard)
  • Pricing
  • Features
  • Descriptions

​
Pre-fill Customer Data

In src/components/ProductCard.astro, replace the hardcoded values with your actual user data: 
customer: {
  name: "John Doe",
  email: "john@example.com",
},

​
Update Customer Portal

In src/components/Header.astro, replace the hardcoded customer ID with the actual customer ID from your auth system or database: 
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 webhook events in src/pages/api/webhook.ts:
  • onSubscriptionActive - Triggered when a subscription becomes active
  • onSubscriptionCancelled - Triggered when a subscription is cancelled
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

This boilerplate uses static output with on-demand rendering for API routes. You’ll need to install an adapter for your deployment platform:
PlatformGuide
VercelDeploy to Vercel
NetlifyDeploy to Netlify
CloudflareDeploy to Cloudflare
See Astro’s deployment guides for all platforms.

​
Update Webhook URL

After deploying, update your webhook URL in the Dodo Payments Dashboard: 
https://your-domain.com/api/webhook
Also remember to update the DODO_PAYMENTS_WEBHOOK_KEY environment variable in your production environment to match the webhook signing key for your deployed domain.

​
Troubleshooting

Delete node_modules and reinstall dependencies:
rm -rf node_modules package-lock.json
npm install
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
For local testing, use ngrok to expose your server:
ngrok http 4321
Update the webhook URL in your Dodo dashboard to the ngrok URL. Remember to update your .env file with the correct webhook verification key.
This boilerplate uses static output with on-demand API routes. You need to install an adapter for deployment:See Astro’s deployment guides for details.

​
Learn More

​
Support

Need help with the boilerplate?