Skip to main content

​
Migration guides

Pick the guide for the version you run today. For the status of every published version, see Versions & Compatibility. For the rules that govern what a release may change, see Versioning & Governance.

​
3.2 migration guides

Moving to 3.2? Start with the 3.1 to 3.2 migration guide. If you pinned a 3.2 beta or release candidate, see the 3.2 prerelease history.

3.1 to 3.2

Compatibility exceptions, mixed-version signing, SDK versions, day-one checklists, and wire changes

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

Reliable Reporting consumer status

Adopt the opt-in sync_reporting_status loop ahead of its active breaking-change notice

​
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

​
Migrating from v2 to v3

This section 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 SDKs see Choose your SDK.
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