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

Which releases a storefront advertises

An Apostra storefront lists 3.0, 3.1, 3.2 and 3.3-beta.6 in supported_versions. A storefront backed by a sales adapter lists 3.1 and 3.2. It cannot truthfully project the 3.0 signal listings and does not yet serve the 3.3 beta. A request that pins 3.3-beta.6 is served at that beta on a storefront that lists it. Other 3.3 beta pins, GA 3.3, and later 3.x pins are served at 3.2. A request that pins no release is served at 3.2. Pin adcp_version: "3.1" to keep receiving 3.1 responses. A request that sends only the legacy adcp_major_version is served at 3.0, the oldest release the storefront lists, because an AdCP 3.0 buyer has no other way to say which release it speaks. On the storefront’s MCP endpoint, pin the release-precision spelling in the tool arguments, for example {"adcp_version": "3.3-beta.6"}. A tools/call that pins the full-semver spelling 3.3.0-beta.6 is refused by the AdCP schema with VALIDATION_ERROR. A response has the shape of the release it was served at. Fields that a later release added are left out, not sent alongside, so a buyer served at 3.1 receives a valid 3.1 response. A request that pins no release receives 3.2 fields. Pin adcp_version: "3.1" to receive a 3.1 response. Some products cannot be expressed at an older release at all, for example a format option whose creative slot uses an asset type that 3.1 does not list. A get_products answer served at 3.1 leaves such a product out and returns every other product. Its errors list then carries a PRODUCT_UNAVAILABLE entry whose details name the left-out products (reason product_invalid_at_adcp_version, with adcp_version, product_ids and, in rules, the field each one failed as a JSON pointer into the product (pointer, for example /format_options/0/format_kind) and the schema rule that refused it (schema_path)). A request pinned to 3.2 receives the products 3.2 can express. A product that does not meet the 3.2 schema is left out of a 3.2 answer the same way, and only the seller can correct it.

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 has not enabled them and expect the storefront to discard them. Dropping operator_unit, currency, timezone, or brand.countries could merge two distinct advertiser accounts. A storefront that has not enabled the 3.2 complete-key accounts serves a 3.2 sync_accounts or list_accounts call exactly as it serves a 3.1 call, as long as the request carries only the fields 3.1 has. For sync_accounts, a request that also carries a 3.2-only identity field is rejected with VERSION_UNSUPPORTED before anything is written. The error identifies the first unsupported field and includes:
A request that pins no release is served at 3.2 but is treated as a 3.1 call for sync_accounts and list_accounts: the storefront admits account identity and lists accounts exactly as it does for 3.1. An explicit adcp_version: "3.2" or "3.3-beta.6" pin opts into the 3.2 complete-key account identity. This is not a refusal to negotiate a same-major release. It means the request itself requires identity semantics that this storefront has not enabled. Retry with the account’s brand and operator only. brand.countries is different on a storefront that has enabled the 3.2 complete-key accounts. It is part of the AdCP 3.2 account key, so that storefront accepts it, and two keys that differ only by brand.countries are two separate seller accounts. Send the codes as ISO 3166-1 alpha-2 values; Apostra stores them sorted and uppercase, so the order and case you send do not matter, and an unassigned code returns INVALID_REQUEST. Omit the field for a global identity: a confirmed identity without a country qualifier covers all countries. Existing identities with an explicit country list retain that scope, while a legacy identity with unknown country scope remains incomplete. Changing the country scope of an existing seller account is a different key, so it creates a new account rather than editing the old one, and historical buys keep their original identity.

What Apostra does

Apostra pins AdCP 3.1 on requests to your sources (and emits the legacy major 3 alongside it for older sources). When a source lists only an older release in supported_versions, Apostra speaks that release to it and converts each request to its shape. A read loses only what the older release cannot express. A change that would lose part of what it asks for, such as a spend cap, a targeting exclusion or any field of a buy update, is refused before anything reaches the source, rather than sent without it. The component catalog requires AdCP 3.1 or newer, so Apostra 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, Apostra 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; Apostra 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, brand.countries among them, 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 Apostra uses AdCP

The buy-side conformance picture