Python

The Python SDK offers a Pythonic interface to the Dodo Payments API, providing both synchronous and asynchronous clients with type definitions for requests and responses. It supports Python 3.9+ and includes comprehensive test coverage.

Installation

Install the SDK using pip:

pip install dodopayments

For enhanced async performance with aiohttp:

pip install dodopayments[aiohttp]

The SDK requires Python 3.9 or higher. We recommend using the latest stable version of Python for the best experience and security updates.

Quick Start

Synchronous Client

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
    environment="test_mode",  # defaults to "live_mode"
)

checkout_session_response = client.checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1
        }
    ],
)
print(checkout_session_response.session_id)

Asynchronous Client

import os
import asyncio
from dodopayments import AsyncDodoPayments

client = AsyncDodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)


async def main() -> None:
    checkout_session_response = await client.checkout_sessions.create(
        product_cart=[
            {
                "product_id": "product_id",
                "quantity": 1,
            }
        ],
    )
    print(checkout_session_response.session_id)


asyncio.run(main())

Always store your API keys securely using environment variables. Never commit them to version control.

Core Features

Pythonic Interface

Clean, idiomatic Python code that follows PEP 8 guidelines and Python conventions

Async/Await

Full support for asynchronous operations with asyncio and optional aiohttp integration

Type Hints

Complete type hints for better IDE support and type checking with mypy

Auto-Pagination

Automatic pagination for list responses with simple iteration

Configuration

Environment Variables

Configure using environment variables:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here

Timeouts

Configure request timeouts globally or per-request:

import httpx
from dodopayments import DodoPayments

# Configure default for all requests (default is 1 minute)
client = DodoPayments(
    timeout=20.0,  # 20 seconds
)

# More granular control
client = DodoPayments(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Override per-request
client.with_options(timeout=5.0).checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1,
        }
    ],
)

Retries

Configure automatic retry behavior:

from dodopayments import DodoPayments

# Configure default for all requests (default is 2)
client = DodoPayments(
    max_retries=0,  # disable retries
)

# Override per-request
client.with_options(max_retries=5).checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1,
        }
    ],
)

Common Operations

Create a Checkout Session

Generate a checkout session:

session = client.checkout_sessions.create(
    product_cart=[
        {
            "product_id": "prod_123",
            "quantity": 1
        }
    ],
    return_url="https://yourdomain.com/return"
)

print(f"Checkout URL: {session.checkout_url}")

Manage Customers

Create and retrieve customer information:

# Create a customer
customer = client.customers.create(
    email="customer@example.com",
    name="John Doe",
    metadata={
        "user_id": "12345"
    }
)

# Retrieve customer
customer = client.customers.retrieve("cus_123")
print(f"Customer: {customer.name} ({customer.email})")

Handle Subscriptions

Create and manage recurring subscriptions:

# Create a subscription
subscription = client.subscriptions.create(
    billing={
        "country": "US",
        "city": "San Francisco",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={"customer_id": "cus_123"},  # or {"email": "...", "name": "..."} for a new customer
    product_id="pdt_456",
    quantity=1,
)

# Charge an on-demand subscription
# product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
charge_response = client.subscriptions.charge(
    subscription_id=subscription.subscription_id,
    product_price=2500,
)

# Retrieve usage history (for metered subscriptions)
usage_history = client.subscriptions.retrieve_usage_history(
    subscription_id=subscription.subscription_id,
    start_date="2024-01-01T00:00:00Z",
)

billing requires at minimum the two-letter ISO country code. customer accepts either {"customer_id": ...} to attach an existing customer or {"email": ..., "name": ...} to create a new one. product_price is in the lowest currency denomination.

Usage-Based Billing

Ingest Usage Events

Track custom events for usage-based billing:

response = client.usage_events.ingest(
    events=[
        {
            "event_id": "api_call_12345",
            "customer_id": "cus_abc123",
            "event_name": "api_request",
            "timestamp": "2024-01-15T10:30:00Z",
            "metadata": {
                "endpoint": "/api/v1/users",
                "method": "GET",
                "tokens_used": "150"
            }
        }
    ]
)

List and Retrieve Events

# Get a specific event
event = client.usage_events.retrieve("api_call_12345")

# List events with filtering
events = client.usage_events.list(
    customer_id="cus_abc123",
    event_name="api_request",
    limit=20
)

for event in events.data:
    print(f"Event: {event.event_id} at {event.timestamp}")

Pagination

Auto-Pagination

Iterate through all items automatically:

from dodopayments import DodoPayments

client = DodoPayments()
all_payments = []

# Automatically fetches more pages as needed
for payment in client.payments.list():
    all_payments.append(payment)
print(all_payments)

Async Pagination

import asyncio
from dodopayments import AsyncDodoPayments

client = AsyncDodoPayments()


async def main() -> None:
    all_payments = []
    # Iterate through items across all pages
    async for payment in client.payments.list():
        all_payments.append(payment)
    print(all_payments)


asyncio.run(main())

Manual Pagination

For more control over pagination:

# Access items from current page
first_page = client.payments.list()
for payment in first_page.items:
    print(payment.brand_id)

# Check for more pages
if first_page.has_next_page():
    next_page = first_page.get_next_page()
    print(f"Fetched {len(next_page.items)} more items")

HTTP Client Configuration

Customize the underlying httpx client:

import httpx
from dodopayments import DodoPayments, DefaultHttpxClient

client = DodoPayments(
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Async with aiohttp

Use aiohttp for enhanced async performance:

import asyncio
from dodopayments import DefaultAioHttpClient
from dodopayments import AsyncDodoPayments


async def main() -> None:
    async with AsyncDodoPayments(
        bearer_token="My Bearer Token",
        http_client=DefaultAioHttpClient(),
    ) as client:
        checkout_session_response = await client.checkout_sessions.create(
            product_cart=[
                {
                    "product_id": "product_id",
                    "quantity": 1,
                }
            ],
        )
        print(checkout_session_response.session_id)


asyncio.run(main())

Logging

Enable logging by setting the environment variable:

export DODO_PAYMENTS_LOG=info

Or for debug-level logging:

export DODO_PAYMENTS_LOG=debug

Framework Integration

FastAPI

from fastapi import FastAPI, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
import os

app = FastAPI()
dodo = AsyncDodoPayments(bearer_token=os.getenv("DODO_API_KEY"))

class CheckoutRequest(BaseModel):
    product_id: str
    quantity: int

@app.post("/create-checkout")
async def create_checkout(request: CheckoutRequest):
    try:
        session = await dodo.checkout_sessions.create(
            product_cart=[{
                "product_id": request.product_id,
                "quantity": request.quantity
            }],
            return_url="https://yourdomain.com/return"
        )
        return {"checkout_url": session.checkout_url}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

Django

from django.http import JsonResponse
from django.views.decorators.http import require_POST
from django.views.decorators.csrf import csrf_exempt
from dodopayments import DodoPayments
import os
import json

client = DodoPayments(bearer_token=os.getenv("DODO_PAYMENTS_API_KEY"))

@csrf_exempt
@require_POST
def create_checkout(request):
    try:
        data = json.loads(request.body)
        session = client.checkout_sessions.create(
            product_cart=[{
                "product_id": data.get("product_id"),
                "quantity": data.get("quantity", 1)
            }],
            return_url="https://yourdomain.com/return"
        )
        return JsonResponse({
            "status": "success",
            "checkout_url": session.checkout_url,
            "session_id": session.session_id
        })
    except Exception as e:
        return JsonResponse({
            "status": "error",
            "message": str(e)
        }, status=400)

Resources

GitHub Repository

View source code and contribute

API Reference

Complete API documentation

Discord Community

Get help and connect with developers

Report Issues

Report bugs or request features

Support

Need help with the Python SDK?

Discord: Join our community server for real-time support
Email: Contact us at support@dodopayments.com
GitHub: Open an issue on the repository

Contributing

We welcome contributions! Check the contributing guidelines to get started.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Installation

Quick Start

Synchronous Client

Asynchronous Client

Core Features

Pythonic Interface

Async/Await

Type Hints

Auto-Pagination

Configuration

Environment Variables

Timeouts

Retries

Common Operations

Create a Checkout Session

Manage Customers

Handle Subscriptions

Usage-Based Billing

Ingest Usage Events

List and Retrieve Events

HTTP Client Configuration

Async with aiohttp

Logging

Framework Integration

FastAPI

Django

Resources

GitHub Repository

API Reference

Discord Community

Report Issues

Support

Contributing

​Installation

​Quick Start

​Synchronous Client

​Asynchronous Client

​Core Features

Pythonic Interface

Async/Await

Type Hints

Auto-Pagination

​Configuration

​Environment Variables

​Timeouts

​Retries

​Common Operations

​Create a Checkout Session

​Manage Customers

​Handle Subscriptions

​Usage-Based Billing

​Ingest Usage Events

​List and Retrieve Events

​Pagination

​Auto-Pagination

​Async Pagination

​Manual Pagination

​HTTP Client Configuration

​Async with aiohttp

​Logging

​Framework Integration

​FastAPI

​Django

​Resources

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​Contributing

Installation

Quick Start

Synchronous Client

Asynchronous Client

Core Features

Configuration

Environment Variables

Timeouts

Retries

Common Operations

Create a Checkout Session

Manage Customers

Handle Subscriptions

Usage-Based Billing

Ingest Usage Events

List and Retrieve Events

Pagination

Auto-Pagination

Async Pagination

Manual Pagination

HTTP Client Configuration

Async with aiohttp

Logging

Framework Integration

FastAPI

Django

Resources

Support

Contributing