Versioning

When we make breaking changes to the Paddle API, we release a new version. We version using sequential numbering.

The current version of the Paddle API is version 1.

Older versions of the API continue to work as before when we release new versions. We don't automatically change your API version, so your integrations continue to work until you're ready to upgrade.

Breaking changes

A breaking change is a change that may require you to make changes to your code to keep your integrations working. They're sometimes called backwards incompatible changes.

Some examples of breaking changes:

• Removing or renaming a parameter or field.
• Removing or renaming an endpoint or operation.
• Removing functionality from an endpoint.
• Adding stricter validation for a field.
• Changing error handling.

We don't automatically change your API version. You can opt in to new versions of the API in the dashboard when you're ready.

Non-breaking changes

We may make non-breaking changes to the API. These are changes that don't disrupt existing workflows, so you can adopt them at your own pace. They're sometimes called backwards compatible changes.

Some examples of non-breaking changes:

• Adding new endpoints or operations.
• Adding new fields to responses.
• Adding new optional request parameters.
• Changing field ordering in responses.

We'll update our developer changelog with information about non-breaking changes.

Your default version

When you sign up for Paddle, the latest version of the Paddle API is set as your default version.

We use this version of the API to respond to API requests where you don't explicitly set a version of the API.

Pin your API version in requests

To specify a version of the Paddle API when making a request, include a Paddle-Version header with your request. For example:

curl https://api.paddle.com/event-types \
  -H "Authorization: Bearer pdl_live_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO" \
  -H "Paddle-Version: 1"

You don't need to specify a version with your request, but it's good practice. Paddle uses your default version when you don't include a version header.

The Paddle-Version header that you send takes priority over your account's default version. This means you can test versions of the API that are later than your default version.

Notification destinations

Webhook destinations don't use your default version. You can set the API version that you want to use when creating a notification destination.

Deprecation

We don't deprecate older versions of our API right now. We'll communicate future announcements around deprecation in plenty of time.