AdCP versioning & negotiation

Interchange and the sources behind your storefront talk to each other over the Ad Context Protocol (AdCP). 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. 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: 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: 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. This is a source-side server issue, not a problem with your account or your buy.

​

Related