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

# Astro Minimal Boilerplate

> Get started quickly with our minimal Astro boilerplate for integrating Dodo Payments into your Astro application

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

<Info>
  This boilerplate uses Astro 5 with TypeScript, Tailwind CSS 4, and the `@dodopayments/astro` adapter.
</Info>

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

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
    cd dodo-astro-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:4321/
    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:4321](http://localhost:4321) to see your pricing page!
  </Step>
</Steps>

## Project Structure

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

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

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

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

This boilerplate uses static output with on-demand rendering for API routes. You'll need to install an adapter for your deployment platform:

| Platform   | Guide                                                                         |
| ---------- | ----------------------------------------------------------------------------- |
| Vercel     | [Deploy to Vercel](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [Deploy to Netlify](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [Deploy to Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |

See [Astro's deployment guides](https://docs.astro.build/en/guides/deploy/) for all platforms.

### Update Webhook URL

After deploying, update your webhook URL in the [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks):

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

<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 4321
    ```

    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/components/Header.astro` with an actual customer ID from your Dodo dashboard.

    Or integrate your authentication system and database to fetch the customer ID dynamically.
  </Accordion>

  <Accordion title="Build fails with adapter error">
    This boilerplate uses static output with on-demand API routes. You need to install an adapter for deployment:

    See [Astro's deployment guides](https://docs.astro.build/en/guides/deploy/) for details.
  </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-astro-minimal-boilerplate) for issues and updates
* Contact our [support team](mailto:support@dodopayments.com) for assistance