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

# API Reference

> REST API for payments, subscriptions, customers, and billing. Authenticate with API keys and handle webhooks for real-time events.

<CardGroup cols={2}>
  <Card title="SDKs & Libraries" icon="code" href="/developer-resources/dodo-payments-sdks">
    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.
  </Card>

  <Card title="Mobile Checkout SDKs" icon="mobile" href="/developer-resources/mobile-integration">
    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.
  </Card>
</CardGroup>

## Environment URLs

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

<Note>
  Learn more about [Test Mode vs Live Mode](/miscellaneous/test-mode-vs-live-mode).
</Note>

## Authentication

API requests require an API key, except a few public endpoints such as [Activate License](/api-reference/licenses/activate-license), [Validate License](/api-reference/licenses/validate-license), and [Deactivate License](/api-reference/licenses/deactivate-license). Generate one in your dashboard and include it in the `Authorization` header of every request.

<Steps>
  <Step title="Generate an API Key">
    Go to **Developer → API Keys** in your dashboard and select **Add API 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`. Give the key a descriptive name and choose your access level:

    * **Enable write access** checked (default): Full read and write permissions for all API operations.
    * **Enable write access** unchecked: Read-only access. You can fetch data (payments, subscriptions, customers, products) but cannot create or modify resources.

    <Tip>
      Uncheck **Enable write access** for integrations that only need to view data, such as analytics tools or dashboard integrations.
    </Tip>
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Authenticate Requests">
    Include your API key in the `Authorization` header of every request:

    ```bash theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    <Warning>
      Never expose your API key in client-side code, public repositories, or version control.
    </Warning>
  </Step>
</Steps>

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

<CodeGroup>
  ```json Success theme={null}
  {
    "payment_id": "pay_gr4RizvMOXFJ6xca3y2tU",
    "status": "succeeded",
    "total_amount": 2999,
    "currency": "USD",
    "created_at": "2024-01-15T10:30:00Z"
  }
  ```

  ```json Error theme={null}
  {
    "code": "INVALID_REQUEST_BODY",
    "message": "Your request body is invalid. Please check your request headers and object."
  }
  ```
</CodeGroup>

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

<Tip>
  To upgrade your rate limit tier, email [support@dodopayments.com](mailto:support@dodopayments.com).
</Tip>

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

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

<CardGroup cols={2}>
  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    Complete list of error codes and their meanings.
  </Card>

  <Card title="Transaction Failures" icon="circle-exclamation" href="/api-reference/transaction-failures">
    Common transaction issues and how to handle them.
  </Card>
</CardGroup>

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

<Card title="Webhook Guide" icon="webhook" href="/developer-resources/webhooks">
  Set up webhooks, handle events, and verify signatures.
</Card>

## Integration Guides

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

<CardGroup cols={2}>
  <Card title="One-time Payments" icon="code-merge" href="/developer-resources/integration-guide">
    Create checkout sessions, payment links, and handle payments.
  </Card>

  <Card title="Subscriptions" icon="credit-card" href="/developer-resources/subscription-integration-guide">
    Set up recurring billing, manage plans, and handle lifecycle events.
  </Card>

  <Card title="Usage-Based Billing" icon="arrow-trend-up" href="/developer-resources/usage-based-billing-guide">
    Meter usage and charge customers based on consumption.
  </Card>

  <Card title="Checkout Sessions" icon="cart-shopping" href="/developer-resources/checkout-session">
    Create secure, hosted checkout experiences.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.