Each request to the Duffel API must include a
Duffel-Version header so we know which
version of the API you want to use.
In our beta version, we may make backwards-incompatible changes to the API at
short notice. When we do, you may need to make changes to your integration, or it'll
When we release a new version of the API, the previous version will be available for 6 months. It will no longer be available or usable after that time.
New API versions will be released with backwards-incompatible changes. Backwards-compatible changes may be added to the latest version. In case we mark parts of the API as deprecated, they'll be removed in the next API version.
Available API versions which predate the latest generally available version will be patched with bug and security fixes, where possible.
Changes in versions
We generally consider the following as backwards-incompatible changes:
Adding a new required request body or query string parameter
Changing the name of a required request body or query string parameter
Removing a required request body or query string parameter
Removing an existing endpoint
Removing any field in the response (whether required or optional)
Restructuring of the input or output format (e.g., making a
top-level field a sub-field, or changing the location of errors to be
Changing a name of a field in the response
Changing a resource name, such as
Changing a HTTP response code
code attributes of API errors
Changing existing behaviour (e.g. segments that were previously returned with a default sorting order not being ordered in that way)
We consider the following as backwards-compatible changes:
Adding a new optional request body or query string parameters
Adding new API endpoints
Adding new attributes to responses from existing API endpoints
Reordering attributes in responses from existing API endpoints
Adding a value to an existing enumeration
Changing format or length of IDs
message attributes of API errors
Adding new types of services, e.g. meals, fast track boarding, and WiFi access.
All of our API changes are posted to our changelog
. Before we make any breaking changes, we'll email details to registered users as well.
For each version, we will publish a migration guide from the previous version to the new one that explains the changes you need to make to upgrade your integration.
The API client libraries which we maintain will be updated when a new version is released so that they're always on the latest version.
Any client library versions that use an older version will eventually stop working as the API version they use falls out of availability.
Versioned instances of client libraries are installed by package managers so you may pin a specific version instead of always updating to the latest version of that package. Our client libraries use semantic versioning
. The version of a client library package will not reflect the API version it uses when connecting to the Duffel API.