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.
Upgrading from 3.0 to 3.1? Use the 3.0 to 3.1 migration guide. This page is for the breaking v2.x to 3.0 upgrade.
Preparing for 3.2? Start with the 3.1 to 3.2 migration guide. During beta, also read the 3.2 beta program for the protocol-first beta.0, initial SDK wave, beta.1 protocol convergence, and exact beta.1 SDK refresh.
v2 has been unsupported since 3.0 GA and reached end of life on August 1, 2026 (UTC). See the v2 sunset page for the full timeline, AgenticAdvertising.org 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. brief is the baseline mode; sellers that declare wholesale or refine in capabilities must handle those mode semantics. 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 supported production posture. Since August 1, 2026, v3-only has been 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 release via adcp_version and sellers advertise accepted releases via adcp.supported_versions. Through 3.x, buyers SHOULD also send the deprecated adcp_major_version, and sellers MUST continue advertising the deprecated adcp.major_versions, for compatibility with older peers. 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.

​
Breaking migrations (v2 → v3.0)

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

​
3.2 migration guides

3.1 to 3.2

Role-based beta checklist, required behavior changes, capability adoption, and rollback

Targeting-aware discovery

Move legacy filters and brief constraints into targeting overlays and support declarations

Media buy status

Remove the deprecated body-level status and use media_buy_status on create/update success

Secured asset access

Replace inline provider credentials with signed URLs or pre-authorized workload identity

Cross-role governance

Adopt the experimental task-scoped authorization and outcome contract as one migration

​
3.1 badge prep guides

You can stay on 3.0 without breaking compatibility. To claim the 3.1 badge, complete this short prep checklist.

3.1 badge checklist

Additive prep for buyers, sellers, agents, SDKs, and compliance workflows

Creative transformers

Move build capability discovery and pricing from formats to transformers