API Reference - Dodo Payments Documentation

SDKs & Libraries

Official backend SDKs for TypeScript, Python, Go, PHP, Java, Kotlin, C#, Ruby, and Rust. These libraries handle authentication, serialization, and error handling so you can focus on your integration.

Mobile Checkout SDKs

Open Dodo’s hosted checkout from Android, iOS, React Native, and Flutter apps and get a typed result back in one call. These SDKs hold no API key.

Environment URLs

Test Mode: https://test.dodopayments.com
Live Mode: https://live.dodopayments.com

Learn more about Test Mode vs Live Mode.

Authentication

API requests require an API key, except a few public endpoints such as Activate License, Validate License, and Deactivate License. Generate one in your dashboard and include it in the Authorization header of every request.

Generate an API Key

Go to Developer → API Keys in your dashboard and select Create New Key. Create the key in the mode you want to call: a test mode key works only with https://test.dodopayments.com, and a live mode key works only with https://live.dodopayments.com. Enter a Key Name, then set None, Read, or Write access for each resource, such as Payments, Refunds, Subscriptions, Products, Customers, Webhooks, or Moderation. Write includes Read, and Payouts and Balances are read-only. Use Select all to set every resource at once.A request the key has no access for returns 403 with the INSUFFICIENT_PERMISSION error code. To change a key’s access later, use Edit Permissions on the key.

Grant each key only the access its integration needs. For example, give an analytics tool Read access, and a refunds bot Write access to Refunds and Read access to Payments.

Keys created before per-resource access keep their original reach: a key with write access can read and write every API resource, and a read-only key can read every API resource.

Store Your Key Securely

Copy the key immediately. You won’t see it again. Store it in an environment variable such as DODO_PAYMENTS_API_KEY.

Authenticate Requests

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Never expose your API key in client-side code, public repositories, or version control.

Response Format

Successful requests return 200 or 201 with a JSON body, or 204 with no body. Errors return a 4xx or 5xx status with a JSON body that contains a code and a message.

{
  "payment_id": "pay_gr4RizvMOXFJ6xca3y2tU",
  "status": "succeeded",
  "total_amount": 2999,
  "currency": "USD",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "code": "INVALID_REQUEST_BODY",
  "message": "Your request body is invalid. Please check your request headers and object."
}

Rate Limits

The API enforces two limits at once: a per-second burst limit and a per-minute sustained limit. Limits apply to your business as a whole, across all of its API keys, and depend on your business’s rate limit tier.

Default Tier

Window	Limit
Per Second (Burst)	40 requests
Per Minute (Sustained)	240 requests

Higher Tiers

Businesses with increased API needs can upgrade to higher rate limits:

Tier	Burst (per second)	Sustained (per minute)
Default	40	240
Tier 1	100	1,000
Tier 2	500	5,000

To upgrade your rate limit tier, email support@dodopayments.com.

Unauthenticated Requests

Requests without a valid API key are rate limited by IP address:

Window	Limit
Per Second (Burst)	20 requests
Per Minute (Sustained)	100 requests

Invoice Downloads

The invoice PDF endpoints, such as Get Invoice, GET /invoices/refunds/{refund_id}, and GET /invoices/payouts/{payout_id}, have their own limits:

Scope	Limit
Per record (one payment, refund, or payout)	5 requests per minute
Per client IP address	20 requests per minute

When either limit is exceeded, the endpoint returns 429 Too Many Requests. To fetch many invoices, space out your requests.

Rate Limit Headers

Responses include headers that show your current usage:

X-RateLimit-Limit — Maximum requests allowed in the current window.
X-RateLimit-Remaining — Requests remaining before you hit the limit.
X-RateLimit-Reset — Seconds until the current window resets.

When you exceed the limit, the API returns 429 Too Many Requests. Implement exponential backoff in your retry logic.

Error Handling

To find what an error means and how to resolve it, see the error codes and transaction failures pages.

Error Codes

Complete list of error codes and their meanings.

Transaction Failures

Common transaction issues and how to handle them.

Webhooks

Receive real-time notifications when payments, subscriptions, and other events occur. Set up webhooks in your dashboard and handle the events your integration needs.

Webhook Guide

Set up webhooks, handle events, and verify signatures.

Integration Guides

Start with one of these guides to build your first integration:

One-time Payments

Create checkout sessions, payment links, and handle payments.

Subscriptions

Set up recurring billing, manage plans, and handle lifecycle events.

Usage-Based Billing

Meter usage and charge customers based on consumption.

Checkout Sessions

Create secure, hosted checkout experiences.

SDKs & Libraries

Mobile Checkout SDKs

​Environment URLs

​Authentication

​Response Format

​Rate Limits

​Default Tier

​Higher Tiers

​Unauthenticated Requests

​Invoice Downloads

​Rate Limit Headers

​Error Handling

Error Codes

Transaction Failures

​Webhooks

Webhook Guide

​Integration Guides

One-time Payments

Subscriptions

Usage-Based Billing

Checkout Sessions

Environment URLs

Authentication

Response Format

Rate Limits

Default Tier

Higher Tiers

Unauthenticated Requests

Invoice Downloads

Rate Limit Headers

Error Handling

Webhooks

Integration Guides