Skip to main content
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:
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: 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.

​
A newer request shape cannot be silently downshifted

Release negotiation and request-shape validation are separate. A 3.2 client cannot send account identity fields introduced in 3.2 to a storefront that advertises only 3.0/3.1 and expect the storefront to discard them. Dropping operator_unit, currency, timezone, or brand.countries could merge two distinct advertiser accounts. For sync_accounts, Interchange rejects that shape with VERSION_UNSUPPORTED before writing anything. The error identifies the first unsupported field and includes:
This is not a refusal to negotiate a same-major release. It means the request itself requires identity semantics that do not exist in the release the storefront can serve. Retry with an existing 3.0/3.1 account binding, or wait until get_adcp_capabilities advertises 3.2.

​
What Interchange does

Interchange pins AdCP 3.1 on requests to your sources (and emits the legacy major 3 alongside it for older sources). The component catalog requires AdCP 3.1 or newer, so Interchange does not retry a catalog warm from its current 3.1 pin at 3.0 and never interprets a 3.0 response as a component catalog. A 3.0-only source may still serve compatible live buyer requests through the pass-through path, but its components remain absent until the source supports 3.1. The catalog warmer contains a one-shot compatibility hook for a future pin above 3.1. It can retry only the highest advertised same-major GA release that is at least 3.1 and no newer than the pin. At the current 3.1 pin there is no lower eligible release, so the hook does not fire. If no eligible release exists, Interchange records VERSION_UNSUPPORTED and the source’s products stay absent from the catalog until the source is corrected.

​
When you see VERSION_UNSUPPORTED

At protocol-negotiation time, a VERSION_UNSUPPORTED error has 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. For the component catalog it must also support at least 3.1; Interchange does not mask a 3.1→3.0 gap with a retry.
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. The sync_accounts request-shape gate described above is the separate third case: its details.reason is adcp_3_2_account_identity_not_supported, and its recovery is to stop sending the named 3.2 fields rather than debug source negotiation.

Connect your sales agent

How a source advertises its versions and capabilities

Source diagnostics

Trace why a source’s catalog is empty or a call failed

Errors

The shared error contract, including VERSION_UNSUPPORTED

How Interchange uses AdCP

The buy-side conformance picture