> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.
# AdCP versioning & negotiation
> How Interchange and your sources agree on an AdCP version per request — what gets pinned, when a source must downshift, and what VERSION_UNSUPPORTED actually means.
Interchange and the sources behind your storefront talk to each other over the [Ad Context Protocol (AdCP)](https://docs.adcontextprotocol.org). Like any protocol, AdCP evolves, so every request and response carries a version, and the two sides negotiate which one to use. This page explains that negotiation: what gets pinned, the rule a conformant source must follow, and what to do when you see a `VERSION_UNSUPPORTED` error or an unexpectedly empty catalog.
## What gets negotiated
AdCP negotiates at **release precision** — `MAJOR.MINOR`, e.g. `3.0` or `3.1`. Patches (the third semver segment) are **not** negotiated: a patch by definition introduces no contract change, so a source's exact build is surfaced separately as `build_version` for operational triage only, never for negotiation.
| Field | Sent by | Meaning |
| -------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `adcp_version` | buyer (on a request), source (on a response) | The release-precision version. On a request it's the **pin** the caller declares; on a response it's the release the source **actually served**. |
| `adcp_major_version` | buyer | The **deprecated** legacy integer (e.g. `3`). Superseded by `adcp_version`, but sources must keep honoring it through 3.x (removed in 4.0). A conformant buyer should send **both** so sources that only read the legacy field still negotiate correctly. |
| `supported_versions` | source (on `get_adcp_capabilities`) | The **authoritative** list of release-precision versions a source speaks. Buyers pin against this. The legacy `major_versions` integer array is its deprecated predecessor. |
Pre-release tags (e.g. `3.1-rc`, `3.1-beta`) hang off a release and match **exactly only** — they are never a downshift target for a GA pin.
## The negotiation rule
This is the single load-bearing rule:
A source **must downshift** a buyer's pin to the **highest supported release at or below the pin, within the same major version**, and serve the request. `VERSION_UNSUPPORTED` is reserved **only** for a **cross-major** mismatch — where the buyer pins a major the source does not implement at all.
So if a buyer pins `3.1` and a source supports only `3.0`, that is a *same-major* gap: the source must downshift to `3.0` and serve, **not** return an error. A source that supports major `3` returning `VERSION_UNSUPPORTED` for a `3.1` request is non-conformant.
The major-vs-minor line is the whole rule:
| Buyer pins | Source supports | Conformant behavior |
| ---------- | ---------------------------- | ----------------------------------------------- |
| `3.1` | `3.0` (same major) | Downshift to `3.0` and serve — **not** an error |
| `3.1` | only `2.x` (different major) | `VERSION_UNSUPPORTED` — the one legitimate case |
When a source downshifts, the response's `adcp_version` is set to the release it **actually served**. Clients should validate the response against **that** release's schema, not against their original pin — which is what makes a downshift safe rather than silently lossy.
## What Interchange does
Interchange pins **AdCP `3.1`** on requests to your sources (and emits the legacy major `3` alongside it for older sources).
As a safety net, if a source returns `VERSION_UNSUPPORTED` while Interchange is warming its catalog, Interchange re-issues the request **once** at a downshifted release. The retry target is the highest GA release the source advertises in `supported_versions` that is within our major and at or below our pin — never above the pin, never a pre-release tag. If the source put its supported set only in the error text, we fall back to the major's GA floor (`3.0`).
This is a single-shot mitigation, not a fix. If the downshifted retry also fails, Interchange records the `VERSION_UNSUPPORTED` error and the source's products stay absent from the catalog until the source is corrected.
## When you see VERSION\_UNSUPPORTED
A `VERSION_UNSUPPORTED` error has exactly two causes, and they have different fixes:
1. **Genuine cross-major incompatibility** — the pinned major is one the source does not implement at all (e.g. a source that only speaks major `2`). This is a spec-correct refusal; the fix is to align on a shared major version.
2. **A non-conformant or stale source build** — the source rejects a *same-major* minor it should have downshifted (e.g. it supports `3.0` but rejects a `3.1` request). This is a **source-side bug**: the source must upgrade its AdCP server to a build that performs same-major downshift. Interchange's single retry is only a stopgap; other buyers in the ecosystem won't necessarily have the same fallback.
If a source's catalog is unexpectedly empty and its recent calls show `VERSION_UNSUPPORTED`, cause (2) is the usual culprit — see [Source diagnostics](/v2/storefront/inventory-sources/diagnostics). This is a source-side server issue, not a problem with your account or your buy.
## Related
How a source advertises its versions and capabilities
Trace why a source's catalog is empty or a call failed
The shared error contract, including `VERSION_UNSUPPORTED`
The buy-side conformance picture