> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Versioning Policy
> How Criteo API versions work, what the different version types mean, and how to know when you need to take action.
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:
| Stage | Duration | Description |
| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Release Candidate** | Up to 6 months | Production-ready. Will roll directly into the next stable release. |
| **Stable** | 12 months | Fully supported. No breaking changes — ever. In the final 3 months (months 9–12), `Deprecation: true` appears in response headers and the `Sunset` header shows your exact decommission date. |
| **Decommissioned** | — | Returns `410 Gone`. Fall-forward applies. |
**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
**For early exploration**
* Test brand-new features before they're finalised
* Contracts may change significantly at any time
* Not suitable for production use
URL: `api.criteo.com/experimental/...`
**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)
**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:
```http theme={null}
# 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?
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.
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.
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.
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](/retail-media/changelog/index) · [Marketing Solutions](/marketing-solutions/changelog/index)) 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.
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.
```http theme={null}
# 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.
| Version | Stable release | Deprecated from | Decommission | Status |
| ------- | -------------- | --------------- | ------------ | -------------- |
| 2025-07 | Jul 2025 | Apr 2026 | **Jul 2026** | DECOMMISSIONED |
| 2025-10 | Oct 2025 | Jul 2026 | **Oct 2026** | DEPRECATED |
| 2026-01 | Jan 2026 | Oct 2026 | **Jan 2027** | ACTIVE |
| 2026-07 | Jul 2026 | Apr 2027 | **Jul 2027** | UPCOMING |
| 2027-01 | Jan 2027 | Oct 2027 | **Jan 2028** | PLANNED |
| 2027-07 | Jul 2027 | Apr 2028 | **Jul 2028** | PLANNED |
**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.