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.

We update our developer changelog whenever we change our API or developer tools. Updates include comprehensive information about what's changed and how to upgrade. See: Developer changelog

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.

Specify a version

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.

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

Specify in requests

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

1
2
3
1curl https://api.paddle.com/event-types 
2  -H "Authorization: Bearer bb4e69088ea07a98a90565ac610c63654423f8f1e2d48b39b5" 
3  -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.

You can't use a version of the API that's earlier than your default version.

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.

Deprecation

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

Related entities