FastAPI Boilerplate

GitHub Repository

Source code for the FastAPI and Dodo Payments boilerplate.

Overview

The FastAPI boilerplate is a Python backend with Dodo Payments already connected. It has endpoints that create checkout sessions and Customer Portal sessions, a webhook endpoint that verifies signatures, and a pricing page rendered from Jinja2 templates.

This boilerplate uses FastAPI with async route handlers, Pydantic for validation and settings, and the dodopayments Python SDK. The handlers call the synchronous DodoPayments client. To avoid blocking the event loop, switch to AsyncDodoPayments and await its calls.

Features

The boilerplate includes:

Quick Setup: Go from clone to a running server in about five minutes.
Async Handlers: Route handlers are FastAPI async def functions.
Checkout Sessions: A pre-configured checkout endpoint that uses the Python SDK.
Webhook Handling: A webhook endpoint that verifies each signature with the SDK’s unwrap method.
Customer Portal: An endpoint that creates Customer Portal sessions.
Type Safety: Pydantic models validate request bodies, and the code uses type hints.
Environment Configuration: pydantic-settings loads and validates the configuration from .env.

Prerequisites

Before you begin, you need:

Python 3.9 or later, which the dodopayments SDK requires. Python 3.11 or later is recommended.
pip or uv for package management.
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/fastapi-boilerplate.git
cd fastapi-boilerplate

Create Virtual Environment

Set up an isolated Python environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Or use uv for faster dependency management:

uv venv
source .venv/bin/activate

Install Dependencies

pip install -r requirements.txt

Or with uv:

uv pip install -r requirements.txt

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 Testing Webhooks Locally.

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:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:8000
DODO_PAYMENTS_ENVIRONMENT=test_mode

All four variables are required. app/core/config.py loads them with pydantic-settings, and the app fails to start if one is missing or empty. DODO_PAYMENTS_RETURN_URL is where checkout sends the customer after payment.

Don’t commit your .env file to version control. The repository’s .gitignore already excludes it.

Add Your Products

Replace the sample products in app/lib/products.py with your own. Set each product_id to the ID of a product under Products in your dashboard. The pricing page displays these products.

Run the Development Server

uvicorn app.main:app --reload --port 8000

Open http://localhost:8000/docs to see the interactive API documentation.

Swagger UI lists the /api/checkout/, /api/webhook/, and /api/customer-portal/ endpoints, ready to test.

The root URL, http://localhost:8000, serves the pricing page.

app/main.py calls templates.TemplateResponse("index.html", {"request": request, ...}), a signature that Starlette 1.x no longer accepts, so the pricing page returns a 500 error on a fresh install. To fix it, change the call to templates.TemplateResponse(request, "index.html", {"products": products}).

Project Structure

fastapi-boilerplate/
├── app/
│   ├── main.py             # FastAPI application entry point
│   ├── api/
│   │   ├── checkout.py     # Checkout session endpoint
│   │   ├── portal.py       # Customer portal endpoint
│   │   └── webhook.py      # Webhook handler endpoint
│   ├── core/
│   │   └── config.py       # Environment configuration
│   ├── lib/
│   │   ├── customers.py    # Customer payload helpers
│   │   └── products.py     # Products shown on the pricing page
│   └── templates/
│       ├── base.html       # Base template
│       └── index.html      # Pricing page
├── requirements.txt        # Python dependencies
├── .env.example            # Environment template
└── README.md

API Endpoints

app/main.py mounts each router under an /api prefix:

Endpoint	Method	Description
`/api/checkout/`	POST	Create a new checkout session
`/api/webhook/`	POST	Handle Dodo Payments webhooks
`/api/customer-portal/`	POST	Generate customer portal URL

Each path ends with a slash. FastAPI answers a request to the path without the slash with a 307 redirect, so use the exact path, especially in your webhook URL.

Code Examples

These examples are condensed from the files in app/api/.

Creating a Checkout Session

app/api/checkout.py creates a checkout session and returns its checkout_url. The request body takes a product_id, an optional quantity, and an optional customer object with name and email:

from typing import Optional

from fastapi import APIRouter, HTTPException
from pydantic import BaseModel
from dodopayments import DodoPayments
from app.core.config import settings
from app.lib.customers import CustomerData, to_dodo_customer_payload

router = APIRouter()
client = DodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT,
)

class CheckoutRequest(BaseModel):
    product_id: str
    quantity: int = 1
    customer: Optional[CustomerData] = None

@router.post("/")
async def create_checkout(request: CheckoutRequest):
    try:
        checkout_session = client.checkout_sessions.create(
            product_cart=[{
                "product_id": request.product_id,
                "quantity": request.quantity,
            }],
            customer=to_dodo_customer_payload(request.customer),
            show_saved_payment_methods=True,
            feature_flags={"allow_discount_code": True},
            return_url=settings.DODO_PAYMENTS_RETURN_URL,
        )
        return {"session_id": checkout_session.session_id, "checkout_url": checkout_session.checkout_url}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

Handling Webhooks

app/api/webhook.py verifies the signature with the SDK’s unwrap method, then branches on the event type:

import json

from fastapi import APIRouter, Request, HTTPException
from dodopayments import DodoPayments
from app.core.config import settings

router = APIRouter()
client = DodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT,
    webhook_key=settings.DODO_PAYMENTS_WEBHOOK_KEY,
)

@router.post("/")
async def handle_webhook(request: Request):
    body = await request.body()

    # Dodo Payments follows the Standard Webhooks spec: the signature covers
    # `id.timestamp.body`, so all three webhook-* headers must be passed in.
    try:
        client.webhooks.unwrap(
            body,
            headers={
                "webhook-id": request.headers.get("webhook-id", ""),
                "webhook-signature": request.headers.get("webhook-signature", ""),
                "webhook-timestamp": request.headers.get("webhook-timestamp", ""),
            },
        )
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Webhook verification failed: {e}")

    event_type = json.loads(body).get("type", "")

    if event_type == "subscription.active":
        print("Subscription is active")  # Grant access, update DB, send email
    elif event_type == "payment.succeeded":
        print("Payment succeeded")  # Fulfill order, update DB, send email
    elif event_type == "subscription.cancelled":
        print("Subscription cancelled")  # Revoke access, update user status
    elif event_type == "payment.failed":
        print("Payment failed")  # Notify user, update payment status
    else:
        print(f"Unhandled event type: {event_type}")

    return {"status": "success", "event": event_type}

Customer Portal Integration

app/api/portal.py creates a Customer Portal session for a customer ID and returns the portal link as url:

from fastapi import APIRouter, HTTPException
from pydantic import BaseModel
from dodopayments import DodoPayments
from app.core.config import settings
from app.lib.customers import sanitize_customer_id

router = APIRouter()
client = DodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT,
)

class PortalRequest(BaseModel):
    customer_id: str

@router.post("/")
async def create_customer_portal(request: PortalRequest):
    try:
        customer_id = sanitize_customer_id(request.customer_id)
        portal_session = client.customers.customer_portal.create(
            customer_id=customer_id,
        )
        return {"url": portal_session.link}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

The pricing page in app/templates/index.html sends a hardcoded customer ID (cus_001) to this endpoint, and a hardcoded name and email to the checkout endpoint. Replace them with the signed-in user’s values.

Webhook Events

The handler in app/api/webhook.py branches on these events:

Event	Description
`payment.succeeded`	Payment completed successfully
`payment.failed`	Payment attempt failed
`subscription.active`	Subscription is now active
`subscription.cancelled`	Subscription was cancelled

To handle another event, add a branch for its type, such as refund.succeeded for a refund that processed successfully. For every event type, see the Webhook Event Guide. Add your business logic inside the webhook handler to:

Update user permissions in your database
Send confirmation emails
Provision access to digital products
Track analytics and metrics

Testing Webhooks Locally

Dodo Payments can’t reach localhost. For local development, use a tool such as ngrok to expose your local server:

ngrok http 8000

Add the ngrok HTTPS URL, followed by /api/webhook/, as an endpoint in your Dodo Payments Dashboard:

https://your-ngrok-url.ngrok.io/api/webhook/

Copy the endpoint’s signing secret into DODO_PAYMENTS_WEBHOOK_KEY in .env, then restart the server. The app reads .env only at startup.

Deployment

Docker

The repository doesn’t include a Dockerfile. To run the app in a container, add this Dockerfile to the repository root:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

COPY . . copies every file in the build context, including .env. To keep your keys out of the image, add a .dockerignore file that lists .env. Then build the image and run it with your environment file:

docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo

Production Considerations

Before deploying to production:

Switch DODO_PAYMENTS_ENVIRONMENT to live_mode.
Use a live mode API key from the dashboard.
Add a webhook endpoint for your production domain, and set DODO_PAYMENTS_WEBHOOK_KEY to its signing secret.
Set DODO_PAYMENTS_RETURN_URL to your production URL.
Enable HTTPS for all endpoints.

Troubleshooting

Import errors or missing modules

Make sure your virtual environment is activated and dependencies are installed:

source venv/bin/activate
pip install -r requirements.txt

Server fails to start with Directory 'app/static' does not exist

app/main.py serves static files from app/static, but the repository doesn’t include that directory. Create it with mkdir app/static, then start the server again.

Checkout session creation 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.

The endpoint returns the SDK error in a 400 response. Check the FastAPI logs for detailed error messages.

Webhooks not receiving events

For local testing, use ngrok to expose your server:

ngrok http 8000

In your Dodo dashboard, add an endpoint with the ngrok URL followed by /api/webhook/, including the trailing slash. Copy that endpoint’s signing secret into DODO_PAYMENTS_WEBHOOK_KEY in your .env file.

Webhook signature verification fails

Make sure DODO_PAYMENTS_WEBHOOK_KEY in .env matches the endpoint’s signing secret.
Verify the signature against the raw request body, before you parse it as JSON.
Pass all three webhook-id, webhook-timestamp, and webhook-signature headers to client.webhooks.unwrap(). The Standard Webhooks signature covers id.timestamp.body, not the body alone.

Learn More

Python SDK

Complete Python SDK documentation with async support

Webhooks Documentation

Learn about all webhook events and best practices

Checkout Sessions

Deep dive into checkout session configuration

API Reference

Complete Dodo Payments API 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

GitHub Repository

Overview

Features

Prerequisites

Quick Start

Project Structure

API Endpoints

Code Examples

Creating a Checkout Session

Handling Webhooks

Customer Portal Integration

Webhook Events

Testing Webhooks Locally

Deployment

Docker

Production Considerations

Troubleshooting

Learn More

Python SDK

Webhooks Documentation

Checkout Sessions

API Reference

Support

GitHub Repository

​Overview

​Features

​Prerequisites

​Quick Start

​Project Structure

​API Endpoints

​Code Examples

​Creating a Checkout Session

​Handling Webhooks

​Customer Portal Integration

​Webhook Events

​Testing Webhooks Locally

​Deployment

​Docker

​Production Considerations

​Troubleshooting

​Learn More

Python SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Support

Overview

Features

Prerequisites

Quick Start

Project Structure

API Endpoints

Code Examples

Creating a Checkout Session

Handling Webhooks

Customer Portal Integration

Webhook Events

Testing Webhooks Locally

Deployment

Docker

Production Considerations

Troubleshooting

Learn More

Support