> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt). # Quickstart Everything you need to make your first call to the Paddle API in five minutes. --- The Paddle API is a RESTful JSON API that lets you create, read, and update data in your Paddle Billing system. Use it to integrate Paddle with your app, build custom flows for subscriptions and transactions, or automate tasks. This quickstart walks you through authenticating and making your first request. It takes about five minutes. {% callout type="note" %} This guide is about making requests to the Paddle API from your backend. Don't call the Paddle API directly in your frontend. Use [Paddle.js](https://developer.paddle.com/paddlejs/include-paddlejs.md) with [client-side tokens](https://developer.paddle.com/paddlejs/client-side-tokens.md) instead. {% /callout %} ## Before you begin You need a Paddle account. You can sign up for free: - [**Sandbox account**](https://sandbox-login.paddle.com/signup) — for testing. No real money is involved. - [**Live account**](https://login.paddle.com/signup) — for production use. Requires approval before you can process real transactions. We recommend starting in the sandbox environment. ## Use Postman The fastest way to get started is to fork our Postman collection. Postman walks you through authentication and making your first request. [Fork our Postman collection to get started with the API]() ## Get an API key {% step=true %} {% callout type="warning" %} Treat your API key like a password. Keep it safe and never share it with apps or people you don't trust. {% /callout %} An [API key](https://developer.paddle.com/api-reference/about/api-keys.md) is a secure credential that authenticates requests to the Paddle API. You create one in the Paddle dashboard. {% instruction-steps %} 1. Go to **Paddle > Developer tools > Authentication**. 2. Click the **API keys** tab, then click {% mock-button %}New API key. 3. Enter a name and description, set an expiry date, and [assign permissions](https://developer.paddle.com/api-reference/about/permissions.md). For this quickstart, we recommend selecting all. 4. Click Save, then copy the key. You can only view it once, so [store it securely](https://developer.paddle.com/api-reference/about/api-keys#best-practices.md). {% /instruction-steps %} {% /dashboard-instructions %} Your API key should be 69 characters long, start with `pdl_`, and contain `apikey_` and either `sdbx_` or `live_`. For example: ```bash {% title="An example sandbox API key" %} pdl_sdbx_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO ``` ## Choose a base URL {% step=true %} Paddle has separate sandbox and live environments. Each has its own base URL and its own set of API keys. | Environment | Base URL | | ----------- | -------------------------------- | | Sandbox | `https://sandbox-api.paddle.com` | | Live | `https://api.paddle.com` | Sandbox keys only work for requests to the sandbox URL, and live keys only work for requests to the live URL. ## Make your first request {% step=true %} The quickest way to verify your setup is to send a request to the `/event-types` endpoint. It returns data even if you have no entities in Paddle and doesn't require any permissions. Pass your API key using the `Authorization` header with the `Bearer` prefix: {% code-group sync="sandbox-live-quickstart" %} ```bash {% title="Sandbox" %} curl https://sandbox-api.paddle.com/event-types \ -H "Authorization: Bearer pdl_sdbx_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO" ``` ```bash {% title="Live" %} curl https://api.paddle.com/event-types \ -H "Authorization: Bearer pdl_live_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO" ``` {% /code-group %} ### Understand the response If the request succeeds, Paddle returns a `200` response with a `data` array and a `meta` object: ```json {% title="Successful response" %} { "data": [ { "name": "transaction.created", "description": "Occurs when a transaction is created.", "group": "Transaction", "available_versions": [1] } ], "meta": { "request_id": "e4aa2cb3-74c7-4e13-9490-1a54fbb7a5c6" } } ``` If something goes wrong, Paddle returns an [error object](https://developer.paddle.com/api-reference/about/errors.md) with an appropriate HTTP status code and a `request_id` you can share with support. ```json {% title="Error response" %} { "error": { "type": "request_error", "code": "invalid_token", "detail": "Authentication token is invalid.", "documentation_url": "https://developer.paddle.com/errors/shared/invalid_token" }, "meta": { "request_id": "e4aa2cb3-74c7-4e13-9490-1a54fbb7a5c6" } } ``` ## Create an entity {% step=true badge="Optional" %} Requests to the Paddle API should be in JSON format. When making requests, specify `application/json` as your `Content-Type`. You can create a customer by sending a `POST` request to the `/customers` endpoint. Your request should be an object that includes `name` and `email`. {% code-group sync="sandbox-live-quickstart" %} ```bash {% highlightLines="3" title="Sandbox" %} curl -X POST https://sandbox-api.paddle.com/customers \ -H "Authorization: Bearer pdl_sdbx_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO" \ -H "Content-Type: application/json" \ -d '{ "name": "Sam Miller", "email": "sam@example.com" }' ``` ```bash {% highlightLines="3" title="Live" %} curl -X POST https://api.paddle.com/customers \ -H "Authorization: Bearer pdl_live_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO" \ -H "Content-Type: application/json" \ -d '{ "name": "Sam Miller", "email": "sam@example.com" }' ``` {% /code-group %} ### Understand the response If the request succeeds, Paddle returns a `201` response with `data` and `meta` objects: ```json {% title="Success response" %} { "data": { "id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4", "status": "active", "custom_data": null, "name": "Sam Miller", "email": "sam@example.com", "marketing_consent": false, "locale": "en", "created_at": "2026-04-11T15:57:24.813Z", "updated_at": "2026-04-11T15:57:24.813Z", "import_meta": null }, "meta": { "request_id": "9bcdcc29-e180-4055-ad3d-d37e5dc5e56d" } } ``` Paddle automatically creates a Paddle ID for new entities, as well as returning fields like `created_at` and `updated_at`. If something is wrong with your request, Paddle returns an [error object](https://developer.paddle.com/api-reference/about/errors.md) like before. Validation errors include an additional `errors` array with details about how to fix. ```json {% title="Validation error" %} { "error": { "type": "request_error", "code": "invalid_field", "detail": "Request does not pass validation.", "documentation_url": "https://developer.paddle.com/errors/shared/invalid_field", "errors": [ { "field": "name", "message": "cannot exceed 1024 characters" } ] }, "meta": { "request_id": "9bcdcc29-e180-4055-ad3d-d37e5dc5e56d" } } ``` ## Pin an API version {% step=true %} When we make breaking changes, we release a new version of the API. Pin the version you're building against using the `Paddle-Version` header so future releases don't break your integration: ```bash {% title="cURL request" highlightLines="3" %} curl https://sandbox-api.paddle.com/event-types \ -H "Authorization: Bearer pdl_sdbx_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO" \ -H "Paddle-Version: 1" ``` The current version of the Paddle API is **version 1**. See [Versioning](https://developer.paddle.com/api-reference/about/versioning.md) for more. ## Next steps You're ready to start building. These reference pages cover the conventions you'll run into across the API: {% card-group cols=3 %} {% card title="Authentication" %} Everything you need to know about [authenticating requests](https://developer.paddle.com/api-reference/about/authentication.md) using Bearer authentication. {% /card %} {% card title="Paddle IDs" %} Every entity has a unique [Paddle ID](https://developer.paddle.com/api-reference/about/paddle-ids.md) that tells you what kind of entity you're working with. {% /card %} {% card title="Data types" %} Paddle uses JSON for requests and responses. See the [data types](https://developer.paddle.com/api-reference/about/data-types.md) used across the API. {% /card %} {% card title="Pagination" %} List endpoints use [cursor based pagination](https://developer.paddle.com/api-reference/about/pagination.md) to let you work with pages of results. {% /card %} {% card title="Filter, search, and sort" %} Most list endpoints support [filtering, searching, and sorting](https://developer.paddle.com/api-reference/about/filter-search-sort.md) using query parameters. {% /card %} {% card title="Related entities" %} Use the `include` parameter to [fetch related entities](https://developer.paddle.com/api-reference/about/include-entities.md) in a single request. {% /card %} {% card title="Errors" %} Learn how [errors](https://developer.paddle.com/api-reference/about/errors.md) are structured and how to troubleshoot common issues. {% /card %} {% card title="Rate limiting" %} See the [rate limits](https://developer.paddle.com/api-reference/about/rate-limiting.md) that apply to the Paddle API and how to handle them. {% /card %} {% card title="Versioning" %} Understand how [API versioning](https://developer.paddle.com/api-reference/about/versioning.md) works and how to opt in to new versions. {% /card %} {% /card-group %}