Skip to main content

​
Migrating from v2 to v3

This page covers every breaking change when upgrading from AdCP 2.x to 3.0, with effort estimates and links to detailed migration pages. For new features see What’s new in v3; for release-candidate deltas see prerelease upgrade notes; for SDK versions that support 3.0 see Schemas and SDKs.
v2 is unsupported as of 3.0 GA and fully deprecated on August 1, 2026 (UTC). See the v2 sunset page for the full timeline, AAO registry policy, and why v2 is not safe for interoperable production.
Starting from v2? See the v3 readiness checklist for the 8 minimum requirements to pass storyboard testing before working through this full migration.
Upgrading from rc.3? The rc.3 → 3.0 prerelease upgrade notes cover additional breaking changes: capabilities model simplification, account required on update_media_buy, preview_creative schema flattening, signal_id required on signals, governance lifecycle changes, and the pending_activation status split.

​
Migration checklist

Each row is a breaking change. Effort indicates the typical work involved:
  • Rename — Field name changed, same semantics. Find-and-replace.
  • Restructure — Shape changed (e.g., string → object, single → array). Requires code changes.
  • Remove — Field existed in v2, removed in v3. Find-and-delete.
  • New requirement — Didn’t exist in v2. Requires new implementation.
buying_mode on get_products is checked by storyboard testing. Sellers must handle all three buying modes (browse, brief, refine). See the v3 readiness checklist for details.

​
New in v3 — required vs optional

These capabilities are new in v3. None existed in v2, so there’s nothing to migrate — but you should know which ones affect your integration.

​
Running v2 and v3 side by side

Dual-support is a temporary migration tool, not a long-term posture. After August 1, 2026, v3-only is the required configuration — see the v2 sunset page. During migration, sellers can accept both v2 and v3 traffic and buyers can route to each seller on the correct version:
  1. Check seller capabilities — Call get_adcp_capabilities on each seller. A successful response means the seller supports v3; buyers declare their version via adcp_major_version and sellers advertise the versions they accept via major_versions. See version negotiation for the full flow. A seller that does not respond to get_adcp_capabilities is v2-only.
  2. Branch by seller — Route v3-capable sellers through your v3 integration and v2-only sellers through your existing v2 code.
  3. Migrate incrementally — Start with the rename changes (pricing fields, channel updates), then tackle structural changes (creative assignments, optimization goals), then adopt new capabilities (accounts, governance) as needed.

​
Deep-dive pages

Channels

native removed, video split, 10 new channels

Pricing

Field renames and price guidance restructure

Creatives

Creative assignments with weights and asset discovery

Catalogs

promoted_offerings to first-class sync_catalogs

Geo targeting

System specification for global geo support

Optimization goals

Single goal to array with discriminated union

Brand identity

brand_manifest to brand ref via brand.json

Signals

Delivery flattening and pricing restructure

Audiences

external_id promotion to required field

Attribution

Integer days to structured Duration objects