Partner API basics

The Paddle partner API is an extension of the public API. It's a subset of the endpoints that we use internally at Paddle to power our dashboard, checkout, and customer portal.

Partner API specifics

You can read the API reference docs to learn about how the Paddle API works. Keep in mind these key differences between the public API and the partner API:

• Partner API keys follow a different format.
• Partner API keys are scoped to all available permissions.
• You must include a Paddle-PartnerID header to identify yourself.
• Partners get higher rate limits, but rate limiting behavior is the same.
• Partners have access to endpoints that are not available to the public. These are marked in the API reference docs.

Partner authentication

All requests to the Paddle API require authentication unless explicitly stated. The API uses Bearer authentication.

Partners must also include a Paddle-PartnerID header to identify themselves.

For example:

Authorization: Bearer {PARTNER_API_KEY}
Paddle-PartnerID: {PARTNER_ID}

For details on how to authenticate, see Authentication.

Partner rate limits

If you send too many requests, the API returns an error with a 429 response code.

Partners get a higher rate limit allowance, but only when Paddle-PartnerID is set. Without it, requests fall back to the per-IP limit.

For details on how to handle rate limiting, see Rate limiting.

API conventions

The Paddle partner API follows the same conventions as the Paddle public API.

Some highlights:

• Two environments: sandbox-api.paddle.com (testing) and api.paddle.com (live).
• All requests are made over HTTPS.
• Requests and responses are in JSON.
• Success responses return 2xx response codes.
• Errors return 4xx or 5xx response codes, with a specific error code.
• Dates and times are in RFC 3339 format.
• Responses include all fields against an entity, returning null values for missing or empty values.
• Currency codes follow ISO 4217.
• Monetary values are strings in the lowest denomination for a currency.
• All entities have a Paddle ID, composed using a prefix + 26 alphanumeric characters.

Success and error responses

When a request is successful, Paddle returns a 2xx response. If there's a response body, it includes a data object or array, and a meta object with details about the request.

When a request fails, Paddle returns an error object with a 4xx or 5xx response code. Errors are consistent and include information to help troubleshoot:

• Use the code to handle errors in your code. This doesn't change.
• Use the documentation_url to get troubleshooting information in the error reference.
• Validation errors return an array of errors to let you know which fields need your attention.
• Every response carries a meta.request_id you can pass to Paddle support to trace a call.

For example:

{
  "error": {
    "type": "request_error",
    "code": "not_found",
    "detail": "Entity pro_01gsz97mq9pa4fkyy0wqenepkz not found",
    "documentation_url": "https://developer.paddle.com/errors/shared/not_found"
  },
  "meta": {
    "request_id": "9346b365-4cad-43a6-b7c1-48ff6a1c7836"
  }
}

{
  "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": "active",
        "message": "must be provided as part of the request"
      },
      {
        "field": "description",
        "message": "maximum length of 256 exceeded. provided value length 653"
      }
    ]
  },
  "meta": {
    "request_id": "9346b365-4cad-43a6-b7c1-48ff6a1c7836"
  }
}

Webhooks

Paddle uses webhooks to push real-time notifications for customer, subscription, and transaction lifecycle events. When integrating with Paddle, sellers use webhooks to handle order fulfillment and entitlements. For example, when a subscription is created, Paddle sends a webhook that you can use to let a user access your app.

Webhooks closely mirror the Paddle API, with a data payload that is the new or changed entity at the time the webhook is sent.

Some high-level details:

• Webhooks have the same top-level structure, including event_id, event_type, occurred_at, notification_id, and data fields.
• If your server doesn't respond with 2xx within five seconds, Paddle retries the notification automatically.
• Use event_id as deduplication key when processing webhooks.
• Events may arrive out of order, so use occurred_at to reason about the sequence of events.
• If your server responds with something other than a 2xx, Paddle retries on an exponential backoff schedule on live and 3 times over 15 minutes on sandbox.
• For security, you must verify webhook signatures using the endpoint secret key.