Versioning Policy

❗️

Deprecated Versions

If you are using one of the following versions and endpoints, we advise you to migrate your applications to a newer version : 2023-04.

Warning

These versions are out of support:

• 2020-10
• 2021-01
• 2021-04
• 2021-07
• 2021-10
• 2022-01
• 2022-04

As the Criteo API continuously evolves, API versioning provides predictability and insight into scheduled changes. This helps you control how you choose to handle feature upgrades and deprecations.

To stay informed about the Criteo API and upcoming changes, you can check the Changelog and make sure your contact info stays up to date.

Release schedule

A new Criteo API version is released every three months at the beginning of each quarter. The version names are date-based by year and month, such as 2020-10. This helps you to know exactly when your version was released.

Each version is supported for 12 months. This means when a new stable version is released and contains changes that affect your integration, you have 12 months to test and migrate to the newest version.

Here is an example release schedule:

❗️

Note about v2020.07

Version 2020.07 is a special version of Criteo API that aggregates the legacy endpoints under the new API framework. Once an endpoint is released under the standard stable version (e.g “2022-10“) you will have 6 months to migrate from v2020.07 to the new version. Please keep an eye on the changelog to be aware of all upcoming changes.

Fall Forward

If your app calls an endpoint on a stable version that is no longer supported, Criteo will fall forward and respond to your request with the same behavior as the oldest supported stable version.

If an endpoint has been removed in all stable versions, then calling such an endpoint on an out-of-support version of Criteo API will result in an error.

See the example table below to understand better a fall-forward mechanism.

Breaking vs. non-breaking changes

Each version might include a number of changes. Here’s what each of them mean.

Breaking change

A breaking change is a change to the API that could cause errors or failures when your app calls the API.

Any change that requires you to change the way you call the API is a breaking change. Another type of breaking change is the deprecation of any functionality previously available in the API. Bug fixes can also create breaking changes if they require you to change how you call the API.

Backward-compatible change

A backward-compatible change is a change that guarantees that any previous requests will still be valid and provide the same output.

Backward-compatible changes include bug fixes or new features that do not interfere with other endpoints or functionality.

Calling an API version

The Criteo API version is explicitly declared in the URL your app call, such as:

https://api.criteo.com/2020-10

At any time, there will be several supported versions of the API available. Specify which version you want to use call by substituting the version name in the URL.

The Criteo API responses will contain the header Criteo-API-Version, which returns the API version that was used to execute the request. If your app is updated, this will match the API version that's specified in your request. If the returned version is different, then your app is out of date and is using the default API version.

Along with the stable versions, there are two unstable versions available: the preview and the beta versions.

Unstable versions

The Criteo API has two unstable versions that include a number of features that may change before their potential inclusion in an upcoming stable version.

Developers are welcome to explore and test the features available in these versions.

Preview version

The preview version lets you see what changes are likely to be released in the next stable version, so that you plan accordingly.

The preview version is based on the latest stable version. Generally, new changes will be in the preview version for at least a month before going to a quarterly stable version.

This version can be called using "preview" as the version number:

https://api.criteo.com/preview

While the changes will likely be released in the stable version, there is always a chance that they might not be released. A feature might be added and removed later before making it to the stable version. Because of this, it’s recommended that you do not use the preview version in your production environment.

If you’re interested in testing the preview version, you can check out its documentation and changelog here.

Deprecation

After 12 months of stability, each Criteo API will sunset and be deprecated. Developers will receive notices when a version is about to be deprecated. These notices will also be posted on the changelog.

To stay informed on version changes and updates to the Criteo API, follow the changelog here.