Skip to main content

​
Migrating to media_buy_status (3.1 → 3.2)

The deprecated response-body status: MediaBuyStatus existed only during the AdCP 3.1 migration window. AdCP 3.2 removes it from create/update success schemas. In 3.2, root status is exclusively the task-envelope status.
AdCP 3.1 splits two enums that 3.0 collided at the same response root key:
  • Envelope status — TaskStatus (submitted / working / input-required / completed / canceled / failed / rejected / auth-required / unknown). Required from beta.2 (#4876).
  • Body media_buy_status — MediaBuyStatus (pending_creatives / pending_start / active / paused / completed / rejected / canceled). New in 3.1.
Under MCP flat-on-the-wire serialization both fields share the response root. In 3.0 they were both named status; the body-level MediaBuyStatus was silently destroyed when the envelope stamped a TaskStatus at the same path. No validator caught it. 3.1 splits them.

​
What changed

​
Before (3.0)

Two keys named status collide at the JSON root under MCP flat serialization — the body-level MediaBuyStatus: 'active' value is silently destroyed by the envelope TaskStatus: 'completed'. No validator catches it.

​
After (3.1)

Two distinct fields. Envelope status carries the task-lifecycle state at the root; body media_buy_status carries the buy’s lifecycle state alongside.

​
3.1 deprecation window (historical)

  • 3.1 sellers SHOULD emit media_buy_status on create_media_buy and update_media_buy success responses. They MAY continue emitting the deprecated top-level status: MediaBuyStatus only while serving 3.1.
  • 3.1 buyers MUST prefer media_buy_status when present. They MAY fall back to legacy status only for a negotiated 3.0 or 3.1 response.
  • 3.0 sellers and buyers continue to work unchanged. No required[] swap, no rename, no breakage.
  • Compliance storyboards assert path: "media_buy_status". A 3.1 seller emitting only the legacy status is schema-valid but fails 3.1 storyboard certification. The storyboard is the binding conformance check; the schema deprecated: true marker is advisory.
  • Sellers emitting both fields MUST emit identical values for media_buy_status and the deprecated status. Divergent emission (e.g., status: "active", media_buy_status: "paused") passes JSON Schema validation but is a conformance violation — 3.1 storyboards enforce equality via field_value_or_absent assertions on status alongside the canonical media_buy_status checks. The if/then JSON Schema constraint was evaluated and deferred: the migration window is short, codegen toolchain compat is uncertain, and the storyboard gate is sufficient. See #4908.

​
SDK behavior during the 3.1 window

In the published 3.1 schema, the legacy status field carries deprecated: true (JSON Schema 2020-12). It is absent from the 3.2 source schema. Deprecation propagation through 3.1 codegen varies: If your 3.1 toolchain doesn’t surface the deprecation, the storyboard gate is your enforcement signal. Regenerating against 3.2 removes the legacy lifecycle field from create/update success types.

​
When the legacy field disappears

  • 3.2 (#4906): the deprecated top-level status: MediaBuyStatus is removed from CreateMediaBuySuccess and UpdateMediaBuySuccess. After 3.2, top-level status on these responses unambiguously carries envelope TaskStatus only. The deprecation window is short by design — the storyboard gate already forces 3.1-conformant sellers off the legacy field.
  • 4.0 (#4905): the nested status cascade lands — media_buys[].status on get-media-buys-response, media_buy_deliveries[].status on get-media-buy-delivery-response, and status on core/media-buy.json rename to media_buy_status. Genuinely breaking (a required[] swap), held to the major.
This removal is the narrow same-major compatibility exception ratified in DR-0011 and tracked by #4906. The repository records it with a minor changeset so it is mechanically released as AdCP 3.2 after the enforced 3.1 deprecation window. The broader nested status cascade remains reserved for 4.0.

​
Forward-compatible buyer code

Code that needs to span 3.0, 3.1, and 4.0 sellers: