Migrating from v2 to v3

A complete guide to migrating AdCP integrations from v2.x to v3.0, with breaking changes, effort estimates, and deep-dive pages for each area.

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.

Area	Change	Effort	Details
Channels	native removed	Restructure	Channels migration
Channels	video split into olv, linear_tv, cinema	Restructure	Channels migration
Channels	10 new channels added (including sponsored_intelligence)	Rename	Channels migration
Pricing	fixed_rate → fixed_price	Rename	Pricing migration
Pricing	price_guidance.floor → floor_price	Rename	Pricing migration
Pricing	Price guidance restructured	Restructure	Pricing migration
Creatives	creative_ids → creative_assignments with weights	Restructure	Creatives migration
Creatives	Asset discovery via assets array	New requirement	Creatives migration
Catalogs	promoted_offerings → sync_catalogs	Restructure	Catalogs migration
Geo targeting	Flat arrays → system specification required	Restructure	Geo targeting migration
Optimization	optimization_goal (single) → optimization_goals (array, discriminated union)	Restructure	Optimization goals migration
Brand identity	brand_manifest → brand ref ({ domain, brand_id })	Restructure	Brand identity migration
Capability discovery	adcp-extension.json → get_adcp_capabilities	Restructure	Capability discovery
Signals	Delivery flattening, pricing restructure	Restructure	Signals migration
Audiences	external_id promoted to required top-level field	Restructure	Audiences migration
Attribution	Integer day counts → Duration objects	Restructure	Attribution migration
Products	buying_mode required on every get_products request	New requirement	get_products reference
Media buy status	pending_activation → pending_start	Rename	Media buys
Media buy status	pending_creatives added (no creatives assigned yet)	New requirement	Media buys
Task status	Legacy task_status and response_status fields MUST NOT be emitted alongside v3 status — remove both	Remove	Task lifecycle
Capabilities	compliance_testing capability block on get_adcp_capabilities	Additive	Capability discovery
Idempotency	idempotency_key required on all mutating requests (UUID v4)	New requirement	Security § Idempotency
Request signing	RFC 9421 Ed25519 signing profile (optional in 3.0, mandatory under AdCP Verified)	Additive	Security § Request signing
Webhook signing	Unified on RFC 9421 profile, baseline-required for sellers; HMAC fallback deprecated (removed in 4.0)	New requirement	Webhooks
Webhook idempotency	idempotency_key required on every webhook payload	New requirement	Webhooks § Reliability
Governance	governance_context is a signed JWS verified via governance agent JWKS	Restructure	Governance
IO approval	MediaBuy.pending_approval removed — approval is a task-layer object	Restructure	Media buy lifecycle
Regulatory invariants	GDPR Art 22 / EU AI Act Annex III enforced via schema if/then	New requirement	Governance § Annex III obligations

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.

Capability	Required?	Who needs it
Accounts protocol (sync_accounts, list_accounts)	Required for all buyers — use sync_accounts when require_operator_auth: false (implicit accounts), list_accounts when true (explicit accounts)	All buyers — the seller’s require_operator_auth flag determines which task to call, not whether accounts are needed
Brand Protocol (brand.json)	Recommended	All buyers — provides brand identity for creative generation
Governance (content standards, property lists)	Optional	Buyers who need brand suitability enforcement
Sponsored Intelligence	Optional	Buyers working with AI platforms that support conversational handoffs
Registry API	Optional	Buyers who want programmatic agent/brand discovery
Campaign Governance	Optional	Organizations with compliance or approval workflows

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