> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-changeset-release-main.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from 3.1 to 3.2

> Role-based migration checklist for adopting the AdCP 3.2 release candidate while preserving 3.1 compatibility.

# Migrating from 3.1 to 3.2

<Warning>
  **3.2 is in release candidate.** RC.0 is the current protocol checkpoint. TypeScript
  `@adcp/sdk@14.0.0-beta.31` and Python `adcp==8.0.0b13` embed RC.0 exactly.
  Python higher-level helpers remain partial, and Go exact
  support remains pending. Keep production traffic pinned to `"3.1"` while
  validating 3.2 in staging.
</Warning>

3.2 is a minor release over 3.1. Existing integrations do not need to adopt the
new compact tools immediately: `get_products`, `create_media_buy`, and
`update_media_buy` remain the 3.x compatibility facades. A caller opts into 3.2
only after the peer advertises the exact release in `supported_versions`.

For the feature narrative, start with [What's New in AdCP 3.2](/dist/docs/3.2.0-rc.1/reference/whats-new-in-3-2).
For prerelease artifacts and SDK timing, use the [3.2 prerelease program](/dist/docs/3.2.0-rc.1/reference/3-2-beta).

## The migration cost is intentional—and bounded

The compact lifecycle adds a second surface during the 3.x compatibility
window because the old facades combine discovery, proposal mutation,
commitment, creation, and operational changes behind overloaded modes. Those
states cannot all be made safe merely by renaming one request.

Use a maintained [AdCP SDK](/dist/docs/3.2.0-rc.1/building/by-layer/L4/choose-your-sdk) for
production wherever possible. The SDK can select an advertised compact tool,
perform a proven direct translation, or run a purpose-built stateful adapter.
It must fail with a typed unsupported-capability error when a legacy peer
cannot preserve immutable proposal history, atomic holds, accepted-term
readback, amendments, or idempotent resume. A generic adapter must never
pretend those semantics exist.

Existing 3.1 implementations remain valid. Adopting 3.2 is an incremental
enterprise migration, not a flag day and not a requirement to reimplement both
surfaces by hand.

## Upgrade checklist

| Step | Who                                | Action                                                                                                                                                        |
| ---- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | Everyone                           | Keep production on `"3.1"`; choose an exact 3.2 prerelease artifact for staging.                                                                              |
| 2    | SDK and codegen maintainers        | Generate from the signed `3.2.0-rc.0` protocol tarball, not `main` or `/schemas/3.2.0-rc.1/`.                                                                 |
| 3    | Sellers and agents                 | Advertise the exact prerelease in `adcp.supported_versions` and echo the release actually served.                                                             |
| 4    | Buyers                             | Send `adcp_version: "3.2-rc.0"` only after exact capability discovery; never silently move between prerelease pins.                                           |
| 5    | Media-buy implementations          | Move create/update success handling completely to `media_buy_status`.                                                                                         |
| 6    | Signing implementations            | Require `content-digest` coverage and migrate request `Signature` and `Content-Digest` binary values to RFC 8941 padded Base64.                               |
| 7    | Creative implementations           | Adopt canonical format capability/product discovery and isolate legacy projection at compatibility boundaries.                                                |
| 8    | Compliance operators               | Test RC.0 from its signed assets or pair `@adcp/sdk@14.0.0-beta.31` or Python `adcp==8.0.0b13` with exact RC.0. Retain the exact package and wire versions.   |
| 9    | Delivery-reporting implementations | Emit and consume currency at media-buy or package grain, move qualified outcomes to `by_package[].metric_values`, and stop producing new `aggregated_totals`. |

## Required to claim 3.2 behavior

### Serve and echo the exact release

During prerelease, version matching is exact. A seller serving RC.0 advertises
`"3.2-rc.0"`. Do not advertise stable `"3.2"` before GA, silently negotiate
between prerelease pins, or treat a major-only declaration as evidence of 3.2
support.

The 3.2 compliance posture makes missing `supported_versions` or a missing
response echo a blocking failure for a 3.2 claim, even though the fields remain
optional at the 3.x schema level for compatibility.

### Use `media_buy_status` on create/update success

AdCP 3.2 removes the deprecated body-level MediaBuyStatus named `status` from
`create_media_buy` and `update_media_buy` success schemas. Root `status` is the
task-envelope state. Read and emit `media_buy_status` for the buy lifecycle.

Nested `media_buys[].status` and `media_buy_deliveries[].status` do not change
until 4.0. See [Migrating to `media_buy_status`](/dist/docs/3.2.0-rc.1/reference/migration/media-buy-status)
for cross-version decoder code.

### Bind every signed request body

Request signing is still optional in 3.2. When a 3.2 endpoint does support
request signing, however, it must advertise
`covers_content_digest: "required"`. Every accepted signature on a request with
a body covers `content-digest`; a signed body without coverage is rejected.

Keep legacy `"either"` or `"forbidden"` behavior on a separately configured
3.0/3.1 compatibility endpoint or disable signing for that endpoint. A field
inside an untrusted request body cannot select a weaker verifier posture.

The request-profile binary encoding also changes in 3.2. Emit `Signature` and
`Content-Digest` values as RFC 8941 `sf-binary`: standard RFC 4648 Base64 using
the `+` and `/` alphabet and required `=` padding inside the `:<base64>:` token.
The 3.0/3.1 request profile used unpadded Base64URL. A 3.2 verifier must reject
that legacy alphabet rather than retrying it through a permissive decoder.

Select the parser from the trusted negotiated endpoint and signing profile, not
from a version field inside the untrusted body. Keep an explicitly routed
3.0/3.1 request endpoint if legacy request signing is required. The separate
`adcp/webhook-signing/v1` profile retains its legacy unpadded Base64URL binary
encoding throughout AdCP 3.x; do not apply the request-profile migration to
webhook receivers. See [Signed requests](/dist/docs/3.2.0-rc.1/building/by-layer/L1/security#signed-requests-transport-layer).

### Emit integer retry delays

3.2 producers emit `error.retry_after` as an integer number of seconds. Clients
that still receive a legacy fractional value should round up before applying
their bounded retry policy. Do not read `retry_after` from `error.data`.

### Move delivery reporting to row-level semantics

The response-wide `currency` and `aggregated_totals` fields on
`get_media_buy_delivery` are deprecated in 3.2 and removed in 4.0. Sellers
SHOULD omit new `aggregated_totals` output. When retaining `aggregated_totals`,
sellers MUST also emit the legacy response-wide `currency` to denominate its
spend. Buyers MUST tolerate both fields being absent and MUST NOT otherwise
treat the legacy currency as an aggregation currency.

For a single-currency media buy, sellers SHOULD emit
`media_buy_deliveries[].currency`; package currencies MUST match it. For a
legacy or externally created mixed-currency buy, omit the row currency and
`daily_breakdown`, and omit monetary or money-derived values from row and
window totals. Report those values only on package rows (including window
package rows) with each package's own currency. AdCP does not define currency
conversion.

Qualified standard delivery metrics move from the deprecated cross-buy
`aggregated_totals.metric_aggregates` array to
`by_package[].metric_values`. Reconcile `committed_metrics`, `metric_values`,
and `missing_metrics` on `(scope, metric_id, qualifier)`. Vendor-defined
delivery continues to use `by_package[].vendor_metric_values`. During migration,
buyers MAY read legacy aggregate rows but SHOULD prefer package values and
calculate a higher-level result only after checking currency, qualifiers,
measurement windows, finality, and deduplication semantics.
When a qualified standard metric is present in `metric_values`, sellers MUST
omit its flat package scalar so consumers never see two sources of truth.

## Adopt by capability

### Compact product and MediaBuy lifecycle

Read `get_adcp_capabilities.media_buy.lifecycle_tools` before choosing a tool.
Use:

* `list_products` for published offer listing;
* `request_proposals`, `refine_proposals`, and `decline_proposals` for immutable
  proposal negotiation;
* `buy_products` for direct purchase;
* `accept_proposal` for committed new-buy, amendment, or negotiated-cancellation
  terms;
* `control_media_buy` for operational controls inside accepted terms.

Absence of the declaration means use the 3.x compatibility facades. Retry a
stateful request with the same tool name, idempotency key, and payload; an
idempotency key does not create replay identity across old and new task names.

### Resolve product, proposal, and live action rights

Use product `allowed_actions[]` only to select offers. Binding rights live in
accepted `commercial_terms.change_terms[]`; the live buy's
`available_actions[]` is the authoritative current-state subset. A 3.2 buyer
uses `available_actions[].change_term_id` to resolve the accepted proposal
term, including its `allowed_statuses`, constraints, mode, and processing SLA.

The `available_actions[].terms_ref` field shipped in 3.1 and remains valid but
opaque. Continue parsing it for 3.1 peers. A 3.2 seller may echo a
`change_term_id` there for an older consumer, but new integrations emit and
prefer `change_term_id`; if both are used as term links, they must agree.
Remove the alias only with AdCP 4.0.

### Targeting-aware discovery

Move structured delivery constraints from briefs and legacy filters into
`targeting_overlay`. Use `required_overlay_support` only for dimensions whose
values will be supplied later. Treat returned configured product IDs as scoped
to their declared lineage, account, cache scope, and expiry.

Follow the complete field map in [Targeting-aware product discovery](/dist/docs/3.2.0-rc.1/reference/migration/targeting-aware-discovery).

### Canonical creative discovery

For new integrations:

* sales agents expose accepted `format_options[]` on products;
* creative agents expose `creative.supported_formats` with stable capability
  IDs and supported operations;
* build and transformer calls select the canonical capability;
* buyers do not require `list_creative_formats` when canonical discovery is
  available.

The compatibility task remains functional on its own schedule. Exact plural
`format_ids` is deprecated in 3.2 for removal in 4.0; singular legacy
`format_id` mappings retain their separate compatibility path.

### Secured assets

Stop producing inline `service_account.credentials`. Prefer a short-lived
asset-scoped signed URL, pre-authorized workload identity, or a bounded bearer
token when the origin requires an Authorization header. Continue parsing the
legacy shape for 3.x compatibility, but never activate received credentials
automatically. See [Migrating secured asset access](/dist/docs/3.2.0-rc.1/reference/migration/asset-access).

### Experimental governance

If you implement `governance.campaign`, update authenticated caller binding,
task-scoped enforcement, intent/execution separation, payload and commitment
binding, and outcome reconciliation together. Do not partially adopt the new
authorization semantics under an old capability declaration.

See [Cross-role governance enforcement](/dist/docs/3.2.0-rc.1/reference/migration/cross-role-governance-enforcement).

## Role-based minimums

| Role                         | Minimum before advertising or sending 3.2                                                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hand-rolled buyer            | Exact prerelease discovery/pin, prerelease-aware schema validation, `media_buy_status` handling, open error-code decoding, and capability gates for every new tool/field. |
| SDK buyer                    | An SDK version that names the exact 3.2 bundle, plus the same capability and prerelease negotiation checks.                                                               |
| Seller                       | Exact release advertisement and echo, 3.1 compatibility routing, canonical status emission, integer retry delays, and truthful task/targeting/format capabilities.        |
| Creative agent               | Canonical supported-format capabilities, operation selection, and explicit compatibility handling for legacy named formats.                                               |
| Signals or measurement agent | Exact prerelease pin and only the attestation, targeting, or feedback capabilities actually implemented.                                                                  |
| Governance provider/service  | Exact prerelease pin, `governance.campaign` experimental declaration, and the complete cross-role authorization migration.                                                |
| SDK maintainer               | Signed RC.0 bundle ingestion, generated-type/validator tests, exact support matrix entry, and protocol feedback destined for the next prerelease.                         |
| Compliance operator          | Matching RC.0 assets and SDK support end to end; no 3.2 badge from a prerelease checkpoint.                                                                               |

## Rollback

Keep the 3.1 handler and schema bundle available throughout prerelease. If a 3.2
staging integration fails:

1. Stop advertising the affected 3.2 prerelease.
2. Re-pin the peer to `"3.1"` only if it advertises 3.1.
3. Route through the 3.x compatibility facades and 3.1 schemas.
4. Preserve the failed prerelease payload and exact artifact version for diagnosis.

Do not retry a 3.2 payload under a 3.1 pin without applying an explicit
version adapter; additive fields and compact task names may not exist in the
3.1 contract.

## Related

* [3.2 prerelease program](/dist/docs/3.2.0-rc.1/reference/3-2-beta)
* [What's New in AdCP 3.2](/dist/docs/3.2.0-rc.1/reference/whats-new-in-3-2)
* [Release Notes](/dist/docs/3.2.0-rc.1/reference/release-notes#version-3-2-0)
* [Versions & Compatibility](/dist/docs/3.2.0-rc.1/reference/versions)
* [Version Adaptation](/dist/docs/3.2.0-rc.1/building/cross-cutting/version-adaptation)