API Versioning Policy - Criteo Docs

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

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 — Deprecation: true appears in response headers 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

Check your status in 30 seconds

Make any API call and look at the response headers:

# This header is on every response — it tells you your current version:
Criteo-API-Version: 2025-10

# These headers only appear when your version is being deprecated:
Deprecation: true
Sunset: Thu, 01 Jan 2027 00:00:00 GMT  # ← your hard deadline

If you see Deprecation: true, action is needed. The Sunset date is the exact date your version stops working.

What does my status mean?

Active — no Deprecation header

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. Deprecation: true will appear in your response headers. Check the Sunset header for your exact deadline and start planning your migration now.

Deprecated — Deprecation: true in responses

Your version is in its final 3 months. The Sunset header shows your exact decommission date. 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 or read Criteo-API-Version from any response.
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.

Set up automated deprecation alerts in your code.

Rather than checking manually, monitor for the Deprecation header on your responses and trigger an alert the first time you see it. This gives you the full 3-month window to plan a migration without any manual monitoring.

# Normal active response — no action needed:
Criteo-API-Version: 2025-10

# Version entering deprecation — act before the Sunset date:
Criteo-API-Version: 2025-10
Deprecation: true
Sunset: Wed, 01 Oct 2026 00:00:00 GMT

# After decommission:
HTTP/1.1 410 Gone

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.