Skip to main content
Criteo releases two stable API versions per year — in January and July. Each version is supported for 12 months. The final 3 months of that period serve as a deprecation window as notice to migrate before decommission.

​
How API versions work

Every API endpoint follows the same lifecycle from initial release to decommission:
Fall-forward: When a version is decommissioned, any endpoint whose contract hasn’t changed is automatically routed to the current stable version — so you won’t always need to update your code. Only endpoints with breaking changes require an explicit migration.

​
The three version types

Experimental

For early exploration
  • Test brand-new features before they’re finalized
  • Contracts may change significantly at any time
  • Not suitable for production use
URL: api.criteo.com/experimental/...

Release Candidate

For integrating early
  • Production-ready — will roll directly into the next stable release
  • Uses the same URL as the upcoming stable version
  • Integrate now, no changes needed when stable ships
  • Only minor changes possible (bug fixes)
URL: e.g. api.criteo.com/2026-07/... (before July 2026)

Stable

For production use
  • Fully supported for 12 months
  • No breaking changes — ever
  • Released every January and July
  • Deprecation notice in the final 3 months (months 9–12)
URL: e.g. api.criteo.com/2026-07/... (from July 2026)
Why use a Release Candidate? The RC and the upcoming stable version share the same URL. If you integrate 2026-07 while it’s still a Release Candidate, you are already on the right version the moment it goes stable — zero migration effort. This replaces the old preview system where integrations had to be re-done once a version became stable.

​
Keeping your integration current

​
What does my status mean?

Active

You’re in good shape. No action needed right now. Keep an eye on the release schedule so you can plan your next upgrade with plenty of lead time.

Active — within 3 months of decommission

You’re entering the deprecation window. Start planning your migration now.

Deprecated

Your version is in its final 3 months. Migrate to the current stable version before that date.

Decommissioned — calls returning 410

Your version is no longer active. Update your base URL to the current stable version immediately. Endpoints that haven’t changed may fall forward automatically — check the changelog to confirm which ones need manual updates.

​
Migrating to a new version

  1. Find your current version — check your API call URL.
  2. Find your deadline — look up your version in the Release Schedule below. The Decommission date is your hard deadline.
  3. Check what’s changed — review the changelog for your API (Retail Media · Marketing Solutions) to identify any breaking changes between your version and the target. Non-breaking additions require no code changes.
  4. Update your base URL — change the version in your URL (e.g. 2025-10 → 2026-07). That’s usually the only change needed.
  5. Test before switching — validate in a test environment before routing production traffic.
  6. Monitor after switching — watch for 4xx / 5xx errors in the first 48 hours. Your old version is still live until its decommission date if you need to roll back.
The easiest migration is one you don’t have to rush. The Release Candidate for the next version is available up to 6 months before its stable release. Integrating early means you upgrade on your own schedule — not against a deadline.

​
Release schedule

Stable versions release every January and July. Each version is supported for 12 months — deprecation begins at month 9, decommission at month 12.
Migrating from Preview? The legacy preview version is being deprecated in 2026. Move any preview integrations to 2026-01 (stable now) or start on the 2026-07 Release Candidate today to be auto-rolled over into the newest stable version.