> ## Documentation Index > Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/reference/whats-new-in-v3); for release-candidate deltas see [prerelease upgrade notes](/docs/reference/migration/prerelease-upgrades); for SDK versions that support 3.0 see [Schemas and SDKs](/docs/building/schemas-and-sdks#adcp-3-0-support). **Upgrading from 3.0 to 3.1?** Use the [3.0 to 3.1 migration guide](/docs/reference/migration/3-0-to-3-1). This page is for the breaking v2.x to 3.0 upgrade. **v2 is unsupported as of 3.0 GA and fully deprecated on August 1, 2026 (UTC).** See the [v2 sunset page](/docs/reference/v2-sunset) for the full timeline, AAO registry policy, and why v2 is not safe for interoperable production. **Starting from v2?** See the [v3 readiness checklist](/docs/reference/migration/v3-readiness) 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](/docs/reference/migration/prerelease-upgrades) 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](/docs/reference/migration/channels) | | Channels | `video` split into `olv`, `linear_tv`, `cinema` | Restructure | [Channels migration](/docs/reference/migration/channels) | | Channels | 10 new channels added (including `sponsored_intelligence`) | Rename | [Channels migration](/docs/reference/migration/channels) | | Pricing | `fixed_rate` → `fixed_price` | Rename | [Pricing migration](/docs/reference/migration/pricing) | | Pricing | `price_guidance.floor` → `floor_price` | Rename | [Pricing migration](/docs/reference/migration/pricing) | | Pricing | Price guidance restructured | Restructure | [Pricing migration](/docs/reference/migration/pricing) | | Creatives | `creative_ids` → `creative_assignments` with weights | Restructure | [Creatives migration](/docs/reference/migration/creatives) | | Creatives | Asset discovery via `assets` array | New requirement | [Creatives migration](/docs/reference/migration/creatives) | | Catalogs | `promoted_offerings` → `sync_catalogs` | Restructure | [Catalogs migration](/docs/reference/migration/catalogs) | | Geo targeting | Flat arrays → system specification required | Restructure | [Geo targeting migration](/docs/reference/migration/geo-targeting) | | Optimization | `optimization_goal` (single) → `optimization_goals` (array, discriminated union) | Restructure | [Optimization goals migration](/docs/reference/migration/optimization-goals) | | Brand identity | `brand_manifest` → `brand` ref (`{ domain, brand_id }`) | Restructure | [Brand identity migration](/docs/reference/migration/brand-identity) | | Capability discovery | `adcp-extension.json` → `get_adcp_capabilities` | Restructure | [Capability discovery](/docs/protocol/get_adcp_capabilities) | | Signals | Delivery flattening, pricing restructure | Restructure | [Signals migration](/docs/reference/migration/signals) | | Audiences | `external_id` promoted to required top-level field | Restructure | [Audiences migration](/docs/reference/migration/audiences) | | Attribution | Integer day counts → `Duration` objects | Restructure | [Attribution migration](/docs/reference/migration/attribution) | | Products | `buying_mode` required on every `get_products` request | New requirement | [get\_products reference](/docs/media-buy/task-reference/get_products) | | Media buy status | `pending_activation` → `pending_start` | Rename | [Media buys](/docs/media-buy/media-buys) | | Media buy status | `pending_creatives` added (no creatives assigned yet) | New requirement | [Media buys](/docs/media-buy/media-buys) | | Task status | Legacy `task_status` and `response_status` fields MUST NOT be emitted alongside v3 `status` — remove both | Remove | [Task lifecycle](/docs/building/implementation/task-lifecycle) | | Capabilities | `compliance_testing` capability block on `get_adcp_capabilities` | Additive | [Capability discovery](/docs/protocol/get_adcp_capabilities#compliance_testing) | | Idempotency | `idempotency_key` required on all mutating requests (UUID v4) | New requirement | [Security § Idempotency](/docs/building/implementation/security) | | Request signing | RFC 9421 Ed25519 signing profile (optional in 3.0, mandatory under AdCP Verified) | Additive | [Security § Request signing](/docs/building/implementation/security) | | Webhook signing | Unified on RFC 9421 profile, baseline-required for sellers; HMAC fallback deprecated (removed in 4.0) | New requirement | [Webhooks](/docs/building/implementation/webhooks) | | Webhook idempotency | `idempotency_key` required on every webhook payload | New requirement | [Webhooks § Reliability](/docs/building/implementation/webhooks) | | Governance | `governance_context` is a signed JWS verified via governance agent JWKS | Restructure | [Governance](/docs/governance/campaign) | | IO approval | `MediaBuy.pending_approval` removed — approval is a task-layer object | Restructure | [Media buy lifecycle](/docs/media-buy/media-buys) | | Regulatory invariants | GDPR Art 22 / EU AI Act Annex III enforced via schema `if/then` | New requirement | [Governance § Annex III obligations](/docs/governance/annex-iii-obligations) | `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](/docs/reference/migration/v3-readiness) 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` (buyer-declared accounts), `list_accounts` when `true` and the seller exposes an account-id namespace | All buyers — the seller's account model 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](/docs/reference/v2-sunset). 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](/docs/reference/versioning#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) `native` removed, `video` split, 10 new channels Field renames and price guidance restructure Creative assignments with weights and asset discovery `promoted_offerings` to first-class `sync_catalogs` System specification for global geo support Single goal to array with discriminated union `brand_manifest` to `brand` ref via `brand.json` Delivery flattening and pricing restructure `external_id` promotion to required field Integer days to structured `Duration` objects ## 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. Additive prep for buyers, sellers, agents, SDKs, and compliance workflows Move build capability discovery and pricing from formats to transformers Split body-level buy status from envelope task status on success responses