## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://developers.criteo.com/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:

| 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

## 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](https://developers.criteo.com/retail-media/changelog/index) · [Marketing Solutions](https://developers.criteo.com/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.

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.

| 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.