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.

Starting from v2? See the v3 readiness checklist for the 7 minimum requirements to pass comply testing before working through this full migration.

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.
• 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

Comply-blocking requirement: buying_mode on get_products is checked by comply 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

During migration, you can run v2 and v3 handlers in parallel. AdCP does not define a version negotiation mechanism at the transport level.

1. Check seller capabilities — Call get_adcp_capabilities on each seller. If it succeeds, the seller supports v3. If the seller only exposes v2 tools (no get_adcp_capabilities), use your v2 code path.
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