Media Buy Specification

​

Abstract

​

Protocol Overview

• Natural language inventory discovery based on campaign briefs
• Campaign creation with package-level budget and targeting
• Creative asset management and synchronization
• Performance tracking and optimization feedback
• Human-in-the-loop approval workflows

​

Transport Requirements

{
  "$schema": "https://adcontextprotocol.org/schemas/3.3.0-beta.0/protocol/get-adcp-capabilities-response.json",
  "status": "completed",
  "adcp": {
    "major_versions": [2],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
  },
  "supported_protocols": ["media_buy"],
  "account": {
    "supported_billing": ["operator", "agent"],
    "supported_account_currency_modes": ["fixed", "per_media_buy"]
  }
}

​

Core Concepts

​

Request Roles

• Orchestrator: The platform making the API request (e.g., DSP, trading desk)
• Account: The billing relationship—who gets billed and what rates apply (identified by account_id)
• Agent: The entity placing the buy (identified by authentication token)

​

Sales Agent Types

• Sales agents MUST only return products for inventory they are authorized to sell
• Sales agents MUST validate authorization via adagents.json when applicable

• Sales agents MUST clearly identify the source publisher for each product
• Sales agents MUST NOT misrepresent inventory provenance

​

Identifiers

• product_id: Opaque identifier for a product returned by get_products. A non-custom wholesale ID remains stable for the same logical offer within the seller and declared cache_scope, including across reads and wholesale-feed webhooks; feed and pricing versions communicate temporal catalog mutation, while retirement or replacement may end the identity. Binding commercial terms are immutable under pricing_option_id, so changed price, floor, currency, model, or priced applicability receives a new option ID. An is_custom: true ID remains stable only in its issuing discovery/refinement lineage through its promised lifetime. Creating a package with the product and pricing-option IDs accepts the disclosed configuration and commercial option. A caller-authorized custom ID past expires_at returns PRODUCT_EXPIRED; after its tombstone is no longer retained or outside its account/lineage, PRODUCT_NOT_FOUND applies without disclosing cross-tenant existence.

​

Structured requirements and briefs

​

Frequency-cap scope and product support

​

Package caps

{
  "overlay_support": {
    "frequency_cap_support": {
      "mutable_fields": ["max_impressions"],
      "supported_control_modes": ["max_impressions"],
      "supported_per_units": ["individuals"],
      "max_impressions_constraints": {
        "minimum": 1,
        "maximum": 10
      },
      "window_constraints": [{
        "unit": "days",
        "allowed_intervals": [1, 7, 30]
      }]
    }
  }
}

​

Shared MediaBuy caps

​

Product execution requirements (experimental)

{
  "product_id": "social_app_installs",
  "catalog_types": ["app"],
  "conversion_tracking": { "action_sources": ["app"] },
  "execution_requirements": [
    { "kind": "event_source", "event_types": ["app_install"] },
    { "kind": "catalog", "catalog_types": ["app"] },
    {
      "kind": "downstream_connection",
      "connection": { "connection_type": "publisher_identity", "scope": "identity", "required_for": ["create_media_buy"] }
    }
  ]
}

• All entries are required. Alternatives inside one entry (event_types, catalog_types) are any-of.
• Account-independent. The declaration says what the product needs, not whether the caller’s account has it. It does not change cache_scope, so a public wholesale catalog stays cacheable, and it MUST NOT carry account-specific resource IDs or names. Connection entries carry no resource_ref, connection_id, or expires_at, no status other than unknown, and a required_for that includes create_media_buy when present.
• Complete when present. Together with the required_connections of the format declarations a package selects, the list is complete for this vocabulary: a seller MUST NOT reject a package that satisfies all of them for lacking a resource of an undeclared kind. A connection every package needs, including the advertiser account itself, belongs in execution_requirements; a connection only some formats need (such as a post authorization for published-post formats) stays on the format declaration. Absence of the field means undeclared, not “needs nothing”.
• Declare only what execution needs. Declare event_source only when the product requires event optimization. A pixel wanted only for attribution or reporting is not an execution requirement in 3.2: declaring it would push buyers into an event goal that changes the bidding objective. Closed-loop retail sellers with platform_managed measurement likewise declare event_source only when the package must bind the seller-managed source.
• Coherent with product capabilities. On the full Product, an event_source requirement requires conversion_tracking. On both the full and the canonical product, a catalog requirement requires catalog_types, and every type it lists MUST appear there.
• App promotion. Use catalog_types: ["app"]; app items carry app_id, bundle_id, apple_id, and store_url. Platforms typically promote one app on one store per package, so a seller MAY require the app catalog to resolve to a single item (select it with ids) and treat a multi-item catalog as ineligible. An app_install or other app event source that is not associated with the bound app is also ineligible.
• Rejection. When an event_source or catalog entry is unmet on a buyer-supplied create_media_buy packages[] entry or update_media_buy new_packages[] entry, or when an update removes or replaces a package’s satisfying binding, a seller that declares the requirement MUST return VALIDATION_ERROR with error.field naming the first unmet binding (for example packages[0].optimization_goals on create, or new_packages[0].catalogs on update) and error.details conforming to execution-requirement-unmet.json. reason distinguishes not_bound (nothing referenced), not_found (the referenced resource is not available to the account), and ineligible (the resource exists but does not satisfy the requirement). For not_found and ineligible, sellers SHOULD point field at the offending entry, such as packages[0].optimization_goals[1].event_sources[0]. A seller that also emits issues[] SHOULD emit one entry per unmet requirement in the same order. Unrelated updates to an existing package are not re-checked. An unmet downstream_connection returns AUTHORIZATION_REQUIRED with error.details.missing_connections[].
• Satisfy everything before calling. A package can miss several requirements across both error codes, and a seller may report either first. Buyers SHOULD check every declared entry, and every selected format’s required_connections, before calling rather than fixing one error per retry.
• Proposal execution. Packages a seller derives from create_media_buy.proposal_id are not buyer-supplied, so the rejection rule above does not apply to them in 3.2. How a proposal carries these bindings is tracked with per-account readiness for 3.3.

​

Product identity absence and reach reporting (experimental)

• media_buy_id: Unique identifier for a media buy. Sales agents MUST return this on successful creation. Orchestrators MUST use this for all subsequent operations on the media buy. A media_buy_id is a stable handle to any order in the seller’s ad server that the authenticated account owns — not only orders originally booked via AdCP.
• package_id: Unique identifier for a package within a media buy. Sales agents MUST return this for each package created.
• idempotency_key: Client-generated unique key for safe retries. Sales agents that receive a duplicate key for the same account MUST return the original response rather than re-executing.

​

Account Ownership vs. Creation Surface

• get_media_buys MUST return every media buy owned by the authenticated account — whether created via create_media_buy, via the seller’s native APIs or UI, via manual trafficking, or via legacy/third-party systems — subject only to the declared filters (status_filter, predecessor_media_buy_id, and the like) and pagination.
• Any media_buy_id returned by get_media_buys MUST be a valid argument to get_media_buy_delivery and to update_media_buy for every action listed in its valid_actions.
• A sales agent MUST NOT mark a buy read-only, hide it, or return MEDIA_BUY_NOT_FOUND on the basis that it was not originally booked through AdCP.
• When a specific action is unavailable for business reasons (contractual obligations, platform constraints, policy), the sales agent expresses that by omitting the action from valid_actions, not by refusing the buy from account-scoped listings.
• Creation surface is never a business reason. Sales agents MUST NOT omit an action from valid_actions — or return INVALID_STATE on an otherwise-valid update — solely because the buy was created outside AdCP. valid_actions omissions are legitimate only when grounded in actual contractual, platform, or policy constraints that would apply equally to an AdCP-created buy in the same state. A seller that returns non-AdCP buys with a systematically empty valid_actions is non-conformant, because that behavior is indistinguishable from hiding the buy and defeats the normative intent of the rules above.

​

Partitioning belongs at the account boundary

• Expose the hidden subset as a separate account (or sub-account) the caller is not authorized to reference.
• Within any account the caller is authorized on, return the full set of buys that account owns per the rules above.

​

Media Buy Lineage

• Forward-only. The successor carries predecessor_media_buy_id and lineage_reason, set once at creation on create_media_buy, buy_products, or accept_proposal (when acceptance creates a new MediaBuy). There is no field on the predecessor and no update action: the fields are not part of update_media_buy, and a seller MUST NOT apply them if sent there. Creating a successor MUST NOT change the predecessor’s AdCP-visible state, including status, revision, updated_at, and history[], and MUST NOT add a reverse pointer to it. Canceled and completed buys are never mutated. Creating the successor does not cancel or complete a live predecessor; the buyer does that separately, and this section does not limit how many buys name the same predecessor.
• Same seller, same account. The value MUST be the media_buy_id of an existing buy owned by the same seller and the same account as the request. media_buy_id is seller-namespaced, so cross-seller lineage is not expressible. The predecessor MAY be in any status; it need not be terminal.
• Invalid links are rejected. The seller MUST reject the request with MEDIA_BUY_NOT_FOUND when no such buy is accessible to the caller in the request’s account, and MUST NOT reveal whether the ID exists under another account. It MUST reject with INVALID_REQUEST when predecessor_media_buy_id and lineage_reason are not supplied together, or when an accept_proposal request carries them for a proposal whose proposal_kind is media_buy_update or media_buy_cancellation. A rejected request creates no media buy. Because the link is set once and must name an already-existing buy, a cycle cannot form; there is no depth limit and no lineage-specific error code.
• No silent drop. A seller that receives a schema-valid link it cannot record MUST reject the request with UNSUPPORTED_FEATURE and MUST NOT create an unlinked buy. Because these schemas allow additional properties, a seller that predates lineage may ignore the fields; a buyer therefore reads the echo on get_media_buys after creation and treats its absence as “link not recorded”.
• Closed reason. lineage_reason is renewal, terms_change, migration, sunset, or replacement. replacement is the seller substituting a buy for one it could not fulfill as booked. Reasons outside the enum travel in ext; buyers branch only on the enum.
• Async and replay. A seller SHOULD validate the link before returning a submitted envelope, and the link MUST appear on the completed buy. The fields are part of the request the idempotency key protects: an exact replay returns the stored outcome without re-validating the predecessor, and a changed link under the same key is an idempotency conflict.
• Read and reverse lookup. get_media_buys echoes both fields on every buy created with them and accepts a predecessor_media_buy_id filter that returns the direct successors of a buy in every status. Chains are walked one hop at a time, and the predecessor of a returned buy MAY no longer be retrievable.
• No commercial effect. Lineage is a record, not a contract: it carries no pricing, budget, delivery, or creative inheritance, the seller applies none of the predecessor’s terms to the successor, and the fields are outside any proposal terms digest.

​

Asynchronous Operations

• Synchronous responses: Sales agents MAY return completed results immediately
• Asynchronous responses: Sales agents MAY return status: "submitted" or status: "working" with a task reference
• Human-in-the-loop: Sales agents MAY require internal human review (e.g. IO signing) by keeping the task in status: "submitted" until the reviewer acts. Sales agents MAY also use status: "input-required" when the buyer must respond (e.g. confirm a budget). Human approval is modelled at the task layer — there is no pending_approval MediaBuy status (that value exists only on Account.status for account onboarding review)
• Rejection: Sales agents MAY reject a media buy in pending_creatives or pending_start status when platform setup reveals the order cannot be fulfilled (e.g., inventory sold out, policy issue discovered during ad server setup). Orchestrators MUST treat rejected as a terminal state. If the seller does not want to accept the order at create time, it SHOULD fail create_media_buy with an error rather than creating a media buy in rejected status.

​

Transaction boundaries across lifecycle surfaces

​

Definition pins

​

Covered set

​

Authoring and verification

• A seller MUST emit one pin for every distinct covered reference in purchases[] on every new_media_buy and media_buy_update draft and revision, and MUST NOT emit such terms without the pins. Entries are unique by (ref_kind, reference), with reference compared by its JCS bytes, and ordered by ref_kind, then by the JCS bytes of reference, both compared as UTF-8 bytes, so equal terms always produce equal terms_digest values. An amendment is a new commitment over the whole resulting envelope, so its pins are issued at the current definitions; the prior accepted snapshot is immutable and keeps its own pins. A media_buy_cancellation proposal commits no new reference and carries no pins. Sellers emit pins, and definition_changed, only to callers negotiating AdCP 3.3 or later.
• Only sellers author pins. The request_proposals, refine_proposals, accept_proposal, and buy_products inputs reject definition_pins with INVALID_REQUEST; check_governance is exempt because it carries the seller-authored proposal. A direct buy_products creates the seller-authored pins and the accepted snapshot atomically.
• A revision re-resolves every covered definition and issues fresh pins. A committed proposal is term-preserving, so refine_proposals finalize re-resolves each existing pin and verifies every pin in the batch before taking any hold. If any pin fails, no hold is taken and the entry is outcome: unable with reason_code: definition_changed and a required drifted_pins[] naming each failing pin and the digest the definition resolves to now; its own definition_changed takes precedence over batch_aborted, which the otherwise-eligible siblings return. Only commercial_terms is frozen; forecast may differ between a draft and its committed successor.
• accept_proposal re-verifies every pin before mutating any state, after the cheaper proposal ID, digest, expiry, and authorization checks. A failing pin returns REFERENCE_DEFINITION_CHANGED, one error per drifted pin, with error.field naming the pin (for example commercial_terms.definition_pins[2]) and details.current_content_digest. An idempotent replay of an acceptance that already completed returns the stored result without re-verifying pins. The seller fetches and compares outside the commit, performs no network I/O while holding a lock, and commits only if the proposal state is still the one it verified. finalize likewise runs its authorization and expiry checks before any fetch.
• Resolution uses a copy of the publisher’s document no older than its own HTTP cache validity and in any case no older than 300 seconds: a verifier revalidates an older copy with a conditional request, and the serve-stale-on-error fallback does not apply to pin verification. A verifier fetches each distinct domain once per verification under an aggregate deadline and follows the adagents.json location, authoritative_location, redirect, and size rules unchanged. A document that was fetched and validated but no longer contains the entry means the definition was withdrawn: that is drift, with current_content_digest omitted. A document that cannot be fetched or parsed is transient, not drift: the seller returns SERVICE_UNAVAILABLE at task level without taking a hold or mutating state, with an error message that does not expose the fetch target, resolver detail, or internal addresses. Duplicate IDs in the source array make the definition unresolvable. Document-level context outside the entry (properties[], authorized_agents, tag maps) is outside the pin.
• Accepted terms retain their pins as the historical record. Post-acceptance drift and remedy policy, retention of pinned content, and signal-source signals are not specified in this version.
• Private-list credentials, including auth_token, never appear in a pin. Keeping them out of accepted commercial terms is specified separately from this version’s pins. A readback of accepted terms shows pins as the record of what was resolved at commitment and makes no ongoing integrity claim. check_governance carries a buyer-submitted proposal, so a governance agent treats its pins as unverified claims.

​

Definition pin preimage

1. Take the published entry exactly as parsed from the publisher’s adagents.json, resolved from the same source the seller used for the reference. Apply no schema defaults; an absent member and a null member are different. Every own member is hashed, including one literally named __proto__. An entry that is not I-JSON (RFC 7493), such as one with a lone surrogate, a duplicate member name, a number that is not finite or not exactly representable as an IEEE 754 double, nesting deeper than 64 levels, or an entry or nested element that is not an object, has no JCS form; a verifier treats that definition as unresolvable, which is drift. Pins are computed only from public, unauthenticated sources.
2. Remove the top-level members named in the kind’s exclusion list below. Exclusion applies only to top-level members, and to top-level members of each element of a nested array. Deeper members stay verbatim.
3. For each named set array present, de-duplicate its elements by JCS bytes and sort them ascending by the UTF-8 bytes of their JCS serialization. A nested array is a set array whose elements are projected first, either with another kind’s rules or with element rules given inline for that array (an exclusion list and named set arrays of the element’s own).
4. Serialize with RFC 8785 (JCS), compute SHA-256 over the UTF-8 bytes, and encode as lowercase hex with no algorithm prefix.

​

Media Buy State Transitions

create_media_buy ──┬──▶ pending_creatives ──▶ pending_start ──▶ active
                   ├──▶ active ──(pause)──▶ paused
                   └──▶ paused (when created with paused: true)

paused ──(resume)──▶ active
active ─────────────▶ completed (terminal)
paused ─────────────▶ completed (terminal)

pending_creatives ──▶ rejected (terminal)  — seller rejects during setup
pending_start ──────▶ rejected (terminal)  — seller rejects during setup

Any non-terminal ──── update(canceled: true) ──▶ canceled (terminal)

• Sales agents MAY return active, paused, pending_creatives, or pending_start from create_media_buy (seller’s choice based on platform setup time and the buyer’s create-time paused request)
• Sales agents MUST transition committed media buys (confirmed_at non-null) from pending_start to active when the flight date arrives. A provisional buy (confirmed_at: null) never auto-activates; see Provisional buys. Sales agents SHOULD notify orchestrators via webhook when this transition occurs.
• A successful committed create_media_buy response constitutes order confirmation. Sales agents MUST include confirmed_at in create/get responses; the value is the seller commitment timestamp, or null for a provisional buy that exists but is still waiting for seller commitment.
• Sales agents MUST include revision in create, get, and update responses. The revision number MUST advance on every committed change to the state get_media_buys reports, whatever the change’s origin; see Revision and confirmation semantics.
• active ↔ paused transitions use update_media_buy with paused: true or paused: false
• create_media_buy with top-level paused: true creates a held media buy when it would otherwise be active. Setup blockers still take precedence: no creatives yields pending_creatives, and a future flight yields pending_start until the start condition is satisfied. The hold is latent while those blockers are visible; once creatives are present and the flight can start, the buy enters paused instead of active.
• update_media_buy with paused: false resumes a buy that is currently paused or clears a latent create-time hold while the visible state is still pending_creatives or pending_start. Clearing a latent hold does not bypass setup blockers; the visible status remains pending until creatives are supplied and the flight can start.
• active or paused → completed when the flight ends, goal is met, or budget is exhausted (seller-initiated)
• Buyer-initiated cancellation uses update_media_buy with canceled: true and optional cancellation_reason
• On the update_media_buy compatibility facade, root canceled: true takes precedence over package cancellation and every other requested mutation. The seller cancels the whole MediaBuy, releases all of its package assignments, ignores every other field except cancellation_reason, and SHOULD return a structured warning identifying the ignored fields. A package-only cancellation is evaluated only when root canceled is absent. Compact control_media_buy instead makes root cancellation mutually exclusive with package and other controls, so a mixed compact request is invalid rather than precedence-resolved.
• Seller-initiated cancellation (e.g., policy violation, inventory withdrawal) transitions the media buy to canceled with cancellation.canceled_by: "seller"; buyers recover the state through get_media_buys. A durable resource-scoped status webhook remains reserved for the 4.0 notification model—operation-scoped push_notification_config is not a future lifecycle subscription. A 3.2 seller advertising account.change_feed with media_buy coverage instead emits the generic account-anchored account.change_recorded invalidation, which the buyer repairs through get_media_buys; it is not a resource-status payload.
• Seller-initiated rejection (from pending_creatives or pending_start) is likewise observable through get_media_buys; implementations MUST NOT synthesize an operation-completion webhook after the originating operation has already completed.
• Sales agents MUST include a cancellation object with canceled_at and canceled_by when transitioning a media buy or package to canceled
• Sales agents MAY reject buyer cancellation of a non-terminal media buy with error code NOT_CANCELLABLE (e.g., when the seller contractually refuses mid-flight cancellation)
• When a buyer attempts to cancel a media buy already in canceled (canceled: true on a canceled buy), sales agents MUST reject with NOT_CANCELLABLE
• All other updates to media buys in terminal states (completed, rejected, canceled) — including canceled: true attempts against completed or rejected buys — MUST be rejected with INVALID_STATE
• Rejection (rejected status) is only valid from pending_creatives or pending_start. Sales agents MUST NOT reject media buys that have already transitioned to active.
• The base 3.x media-buy wire does not define a durable seller-initiated resource-status subscription. Sellers MUST preserve the transition in MediaBuy readback and history. In 3.2, a seller MAY provide immediate generic invalidation by advertising the experimental account.change_feed capability (and feature id) with media_buy coverage and accepting an account.change_recorded account subscriber; otherwise buyers needing immediate push delivery require an implementation extension until the 4.0 resource-scoped notification contract lands.
• The canceled field on update requests uses "const": true — only true is valid. Sending canceled: false fails schema validation. Cancellation is irreversible; there is no “uncancel” operation.
• Creative assignments are released on buy rejection or cancellation. When a media buy transitions to rejected or canceled, all package-creative assignments on that media buy are released. For sellers that advertise creative.has_creative_library: true, the creatives persist in the creative library per assignment state and creative state and MAY be referenced by creative_id in a subsequent create_media_buy or sync_creatives call. Inline-only sellers that advertise inline_creative_management without a creative library MAY keep submitted creatives package-scoped; they do not advertise cross-buy reuse or list_creatives readback.
• Creative review is independent of buy outcome. Sales agents MUST NOT implicitly reject a creative because its containing buy was rejected; a creative rejection MUST be a deliberate review decision with its own rejection_reason. If the buy was rejected because a creative violated content policy, the sales agent MAY reject that creative — but only via the normal review path with its own rejection_reason; the buy’s rejected status is not itself sufficient.
• Observability of released assignments. The media-buy-level canceled or rejected transition, preserved in get_media_buys status and history, IS the audit record for all its released assignments; buyers MUST NOT rely on per-assignment diff observability. A negotiated implementation webhook extension may accelerate discovery but is not required by 3.x. Released assignments no longer appear in get_media_buys responses for that buy. Buyers confirming library reusability SHOULD call list_creatives to verify the creative is still in the library and observe its current status. Inline-only buyers should retain their submitted creative bodies because get_media_buys surfaces package-level approval state, not full creative-body retrieval. Package-scoped deadlines (creative_deadline) on the prior package have no bearing on a library creative’s eligibility for a new buy.
• Retention. Sales agents with creative libraries SHOULD retain released creatives in the library for at least 90 days after the last assignment is released. A normative retention floor is specified in the creative retention contract tracked under #2260; until that contract lands, buyers relying on long-horizon reuse SHOULD verify persistence via list_creatives before referencing a released creative on a new buy.

​

Revision and confirmation semantics

• an AdCP task, from any authorized principal;
• a seller operator, for example an edit in the seller’s own console or ad server;
• seller automation, for example a policy action, an expiry or an approval decision; or
• a connected platform, whose change the seller observes and ingests.

​

Provisional buys (seller review hold)

• Two independent axes. status (media_buy_status on create_media_buy, status on get_media_buys) is the buyer-actionable readiness axis. confirmed_at is the seller-commitment axis. Commitment is keyed off confirmed_at, never off status. A provisional buy reports the status it will have on confirmation: pending_creatives while creatives are missing or unapproved, pending_start once the buy is otherwise ready. Neither value means the seller has accepted the buy, and active is not permitted.
• Confirmation is a state change. When the seller commits, it sets confirmed_at exactly once and, as for every mutating state change, increments revision. The status after confirmation follows the ordinary lifecycle for the buy’s creative readiness and flight.
• Idempotency replay. An exact replay of the original create_media_buy returns the original response, including confirmed_at: null and the original revision, even after the seller has confirmed. Buyers read current state through get_media_buys; a replay never shows the confirmed state and never increments revision.
• Rejection and cancellation. The seller MAY reject a held buy (status: rejected, with rejection_reason), and the buyer MAY cancel it with update_media_buy (canceled: true). In both cases confirmed_at stays null: a buy that was never committed does not acquire a commitment timestamp by ending.
• Pause and resume. The valid_actions table lists pause for pending_creatives and pending_start regardless of commitment. A buyer pause on a held buy sets the same latent create-time hold described above and does not commit the seller or change confirmed_at. A seller that does not accept buyer pause or resume on a buy it is still reviewing SHOULD omit them from valid_actions and reject the request with INVALID_STATE.
• Flight start before confirmation. Because a provisional buy MUST NOT be active, the pending_start to active transition does not occur for it. A held buy whose flight start passes stays pending_start until the seller either confirms it (after which it follows the ordinary lifecycle, so a confirmed buy whose flight has begun and whose creatives are ready is active) or rejects it. Sellers SHOULD confirm or reject before the flight start.
• Expected confirmation time. A seller MAY expose an informational expected_confirmation_at on get_media_buys while confirmed_at is null, such as the end of a review window or the next ad-server read-back. It is absent once confirmed_at is set. It is not an SLA or an expiry, no seller or buyer behavior depends on it, and buyers MUST key commitment off confirmed_at, never off this field.
• Commitment waits on read-back. A seller whose commitment waits on ad-server read-back keeps confirmed_at: null until the check passes, and the buy reports pending_start or pending_creatives meanwhile.
• Observation is by polling. Confirmation, rejection, and seller cancellation are observable through get_media_buys. The media-buy wire defines no status-change webhook, so buyers cannot rely on one; a seller advertising the experimental account.change_feed capability with media_buy coverage MAY emit its generic invalidation, which the buyer repairs through get_media_buys.

• Packages MAY have a creative_deadline — after this deadline, creative changes to the package are rejected with CREATIVE_DEADLINE_EXCEEDED. When absent, the media buy’s creative_deadline applies. CREATIVE_REJECTED covers content-policy, brand-safety, and accessibility-review failures.
• Package cancellation (canceled: true in a package update) is irreversible and independent of the media buy’s status — a single package can be canceled while the media buy remains active. Creative assignments on the canceled package are released per the media-buy-level rule above; creatives assigned to other active packages on the same media buy are unaffected.
• Sales agents MUST retain delivery data for canceled packages. When include_snapshot is true, sales agents SHOULD return a final snapshot reflecting delivery state at the time of cancellation.
• When all packages in a media buy are canceled, the media buy itself remains in its current status (active or paused). Sellers that support mid-flight package additions advertise add_packages in valid_actions — the buyer can add new packages via new_packages in update_media_buy. Otherwise, the buyer SHOULD explicitly cancel the media buy. Sales agents SHOULD notify orchestrators (via context.notes in the update response) when the last active package is canceled. Sales agents MAY auto-transition the media buy to canceled after a seller-defined grace period if no new activity occurs.

​

Creative Approval on Packages

1. Check rejection_reason on get_media_buys response
2. Fix the creative (update assets, adjust manifest)
3. Resubmit via sync_creatives for library-backed sellers, or via packages[].creatives on update_media_buy for inline-only sellers
4. Approval resets to pending_review

​

Verification Tag Enforcement

​

Tasks

​

get_products

• Orchestrators MUST set buying_mode to "brief", "wholesale", or "refine"
• Orchestrators MUST include brief when buying_mode is "brief"
• Orchestrators MUST NOT include brief when buying_mode is "wholesale" or "refine"
• Orchestrators MUST include refine when buying_mode is "refine"
• Orchestrators MUST NOT include refine when buying_mode is "brief" or "wholesale"
• Orchestrators MUST provide scope and product_id for each product entry in refine, and scope and proposal_id for each proposal entry
• Orchestrators MAY omit action on product and proposal entries (defaults to "include")
• Orchestrators MUST NOT include multiple entries for the same product ID or proposal ID in a single refine array
• Sales agents MUST return products matching the brief criteria when a brief is provided
• Sales agents MUST include product_id and pricing_options for each product
• Sales agents SHOULD include relevance scoring when multiple products match
• Sales agents that understand a well-formed brief or refine request but deliberately decline to offer products for commercial, availability, or seller-policy reasons MUST return the GetProductsRejected arm with status: "rejected" and a buyer-facing reason
• Sales agents MUST NOT use GetProductsRejected for a completed search with no matching inventory, incomplete work, or a technical failure: use status: "completed" with products: [], a usable partial response with incomplete[] / an async task arm, or the error channel respectively
• incomplete[] describes missing scopes in an otherwise usable response; it does not classify the condition as retryable. A timeout or unavailable upstream that prevents a usable response MUST use the error channel, normally SERVICE_UNAVAILABLE with error.recovery: "transient" and optional retry_after
• Sales agents using GetProductsRejected MUST NOT also return products, proposals, incomplete, filter_diagnostics, refinement_applied, cache_scope, errors, or envelope-level adcp_error; the task completed successfully with a structured business outcome rather than a full or partial search result
• Orchestrators receiving GetProductsRejected MUST treat the transport call as successful, dispatch on status: "rejected", and use suggestions[] when present to decide whether to revise and resubmit the brief

• Sales agents MUST treat a missing action on product and proposal refine entries as action: "include"
• Sales agents MUST omit products with action: "omit" from the response
• Sales agents MUST omit proposals with action: "omit" from the response
• Sales agents MUST return products with action: "include", with updated pricing
• Sales agents SHOULD fulfill the ask on product entries with action: "include"
• Sales agents SHOULD return additional products similar to those with action: "more_like_this", plus the original product
• Sales agents SHOULD consider request-level asks (scope: "request") when composing the response — this MAY result in additional products beyond those explicitly referenced. Per-product actions take precedence over request-level direction.
• Sales agents SHOULD fulfill the ask on proposal entries with action: "include"
• Sales agents SHOULD include refinement_applied in the response, with one entry per change request matched by position
• Sales agents that return refinement_applied MUST echo scope on each entry and MUST echo product_id / proposal_id for product and proposal scopes, so orchestrators can cross-validate alignment
• Sales agents MAY return proposals alongside products in refine mode, even when the orchestrator did not include proposal entries

​

Canonical creative-format discovery

• Publisher acceptance: publisher adagents.json.formats[]
• Sales-agent deliverability: get_products Product.format_options[]
• Creative production/validation/preview: creative agent get_adcp_capabilities.creative.supported_formats[]

• Sales agents MUST publish the closed sellable format set on every product’s canonical format_options[]
• Placement-level declarations MAY narrow, but MUST NOT broaden, the product set
• Sales agents MUST NOT present publisher-catalog formats as if every declared format were deliverable by that agent
• Compatibility list_creative_formats responses MAY be projected from canonical declarations for older 3.x peers, but MUST NOT be independently authored

​

create_media_buy

• Orchestrators MUST include either packages array or proposal_id
• Orchestrators MUST include start_time and end_time for the campaign
• Orchestrators MAY include predecessor_media_buy_id with lineage_reason to link the new buy to an earlier buy of the same seller and account; see Media Buy Lineage
• Sales agents MUST return media_buy_id on successful creation
• Sales agents MUST return confirmed_at on successful creation. The value is the seller commitment timestamp, or null when the response creates a provisional buy that is not yet committed.
• Sales agents MUST return revision on successful creation
• Sales agents MUST return creative_deadline indicating when creatives must be uploaded
• Sales agents MUST validate budget against pricing options
• On validation failure, sales agents MUST return an errors array

​

update_media_buy

• Orchestrators MUST include media_buy_id
• Sales agents MUST accept any media_buy_id returned by get_media_buys for the authenticated account and MUST NOT refuse updates on the basis that the buy was originally created outside AdCP. Business constraints on specific operations are expressed by omitting them from valid_actions. See Account Ownership vs. Creation Surface.
• Sales agents MUST apply PATCH semantics: only specified fields are updated; omitted fields remain unchanged. Within a request-side package targeting_overlay, this rule applies per dimension: omission preserves the dimension, a non-null value replaces it, and null clears it. Successful response and readback schemas contain only the resulting non-null targeting state.
• When a buyer attempts to cancel a media buy already in canceled (canceled: true on a canceled buy), sales agents MUST reject with NOT_CANCELLABLE
• All other updates to media buys in terminal states (completed, rejected, canceled) — including canceled: true attempts against completed or rejected buys — MUST be rejected with INVALID_STATE
• Orchestrators MAY cancel a media buy by setting canceled: true with optional cancellation_reason
• Sales agents MUST transition the media buy to canceled status upon accepting cancellation
• Sales agents MAY reject cancellation of a non-terminal media buy with error code NOT_CANCELLABLE
• Orchestrators MAY cancel individual packages by setting canceled: true on a package update
• Sales agents MUST reject creative changes to packages past their creative_deadline with error code CREATIVE_DEADLINE_EXCEEDED
• Orchestrators MAY add new packages to an existing media buy via new_packages. Sales agents that support this MUST advertise add_packages in valid_actions. Sales agents that do not support adding packages MUST reject with UNSUPPORTED_FEATURE.
• When root canceled: true is present alongside other fields in an update request, including packages[].canceled, sales agents MUST cancel the whole MediaBuy and MUST ignore all other fields except cancellation_reason. Root cancellation takes precedence over package cancellation and other concurrent mutations. Sales agents SHOULD include a structured success warnings[] entry naming ignored fields; warnings no longer belong in opaque context. Package cancellation is evaluated independently only when root canceled is absent. Within a package update, canceled: true likewise takes precedence over that package’s sibling fields: apply only its cancellation and reason and warn about ignored siblings. Root fields and other package entries still apply atomically unless root cancellation is present.
• Sales agents MUST return affected_packages containing the state of each directly modified package after the update is applied (or the proposed state if pending approval); an empty array is valid when only campaign-level fields (e.g., paused, start_time) are updated
• When manual approval is required, sales agents MUST persist the pending update request, MUST return implementation_date: null, and MUST NOT return empty affected_packages
• Sales agents SHOULD return the updated media buy state

​

sync_catalogs

• Orchestrators MUST include account_id
• When catalogs is provided, it MUST contain at least one catalog
• When catalogs is omitted, the call is discovery-only and returns existing catalogs without modification
• Sales agents MUST return per-catalog outcomes, including what action was taken and any item-level issues
• Sales agents SHOULD support dry_run for validation without applying changes

​

list_creatives

​

sync_creatives

​

get_media_buys

• Orchestrators MAY filter by account_id, media_buy_ids, status_filter, and predecessor_media_buy_id (direct successors of a buy; see Media Buy Lineage)
• Sales agents MUST echo predecessor_media_buy_id and lineage_reason on every media buy created with them
• Orchestrators SHOULD use cursor pagination (pagination.max_results / pagination.cursor) for broad scope queries
• Sales agents MUST return every media buy owned by the authenticated account that matches the declared filter set, regardless of how the buy was created (AdCP, seller’s native APIs/UI, manual trafficking, legacy systems). See Account Ownership vs. Creation Surface.
• Sales agents MUST return current media buy status and package-level operational state for each matched media buy
• Sales agents SHOULD include status_as_of when the returned media-buy-level status is served from a cache or computed as a rolled-up status from upstream legs. For rolled-up statuses, status_as_of MUST NOT be later than the oldest upstream status observation that could affect the returned roll-up, so it never overstates freshness. Omit it or return null to make no freshness assertion; buyers MUST NOT infer that an omitted or null value means the status is live. Buyers use status_as_of to interpret list-status freshness; updated_at remains the media buy’s last modification time.
• Sales agents SHOULD include valid_actions for each media buy, listing the actions the buyer can perform in the current state. This eliminates the need for agents to internalize the state machine. Expected mapping:

• Orchestrators MAY request revision history by setting include_history to the number of most-recent entries desired. Sales agents SHOULD return a history array per media buy when include_history > 0, containing revision number, timestamp, server-derived actor identity, origin (required on entries for changes that did not arrive through an AdCP task), action type, and optional summary. History entries MUST be ordered most-recent-first.
• Sales agents MUST include one media-buy currency for every AdCP-authored buy. total_budget, package budget/minimum constraints, and canonical BiddingPolicy monetary fields use that denomination, and every selected pricing option MUST declare it. Packages requiring another currency belong in a separate media buy. package.currency remains a legacy/external-buy readback field; snapshot.currency may identify an upstream reporting denomination but MUST NOT reinterpret authored budget or bidding values.
• Sales agents SHOULD include creative approval outcomes and pending format requirements when available
• If include_snapshot is true and snapshot data is omitted for a package, sales agents MUST return snapshot_unavailable_reason
• When include_snapshot is true and snapshots are returned, each snapshot MUST include as_of and staleness_seconds
• Default status_filter: ["active"] applies only when both media_buy_ids and predecessor_media_buy_id are omitted

​

Creative state freshness

• Each value is the time of the seller’s last observation of its source of truth for that state. A rolled-up value MUST NOT be later than the oldest upstream observation that could affect it. Omission makes no freshness assertion; buyers MUST NOT infer that the state is live.
• creative_assignments_as_of covers the package’s assignment set, meaning which creatives appear in creative_approvals. A creative absent from the set is absent as of that time. approval_status_as_of covers approval_status, rejection_reason, and approval_scopes. status_as_of covers creative status.
• Accepting an AdCP write (for example, sync_creatives or a creative change on update_media_buy) MUST NOT by itself advance a value. It advances only when the seller observes the resulting state in its source of truth. A seller whose AdCP store is its source of truth observes at commit time.
• A value earlier than the buyer’s last accepted write for that relationship means the seller has not yet confirmed the write, and the returned state predates it. No separate status value is needed for “not known yet.”
• Sales agents SHOULD include these values when the state is served from a cache or from a source that confirms asynchronously, such as a system that confirms assignments a day after the write.
• A change that only advances an *_as_of value MUST NOT fire creative.assignment_changed or creative.status_changed and MUST NOT write an account change record.
• STALE_RESPONSE is the complementary signal: a seller that could not reach its source of truth and served cached state past its freshness target emits it alongside the payload. The *_as_of values report how old each piece of state is in either case.

​

get_media_buy_delivery

• Orchestrators MUST include media_buy_id
• Sales agents MUST accept any media_buy_id returned by get_media_buys for the authenticated account, regardless of creation surface. See Account Ownership vs. Creation Surface.
• Sales agents MUST return delivery metrics at the package level
• Sales agents SHOULD include dimensional breakdowns when requested
• Sales agents MUST include as_of timestamp indicating data freshness

​

provide_performance_feedback

• Orchestrators MUST include media_buy_id and performance metrics
• Sales agents MUST acknowledge receipt of feedback
• Sales agents SHOULD use feedback to optimize delivery within campaign constraints

​

sync_event_sources

• Orchestrators MUST include account_id
• When event_sources is provided, it MUST contain at least one event source
• When event_sources is omitted, the call is discovery-only and returns all event sources on the account without modification
• Sales agents MUST return per-source results with action indicating what happened
• Sales agents MUST include seller-managed event sources in the response when present
• Sales agents SHOULD return setup instructions for newly created event sources
• Sales agents MAY include platform_id for cross-referencing the event source in the seller’s platform; in 3.3 and later 3.x responses they MUST also emit the deprecated seller_id alias with the same value when reporting this identifier

​

log_event

• Orchestrators MUST include event_source_id referencing a configured event source
• Orchestrators MUST include at least one event with event_id, event_type, and event_time
• Sales agents MUST return events_received and events_processed counts
• Sales agents MUST deduplicate events by event_id + event_type + event_source_id
• Sales agents SHOULD report partial_failures for individually failed events
• Sales agents SHOULD return match_quality score when user matching is attempted

​

sync_audiences

• Orchestrators MUST include account_id
• Orchestrators MUST include at least one audience with hashed member data
• Sales agents MUST return per-audience outcomes with matching status
• Sales agents SHOULD support push_notification_config for async matching completion
• Sales agents MUST accept SHA-256 hashed identifiers and MUST reject cleartext email/phone in hashed_email/hashed_phone fields (PII minimization at the transport boundary; see Privacy Considerations for the retention/consent obligations that hashing does not satisfy)

​

Error Handling

• MEDIA_BUY_NOT_FOUND: Referenced media buy does not exist
• PACKAGE_NOT_FOUND: Referenced package does not exist
• PRODUCT_NOT_FOUND: Referenced product does not exist
• PRODUCT_EXPIRED: Referenced configured product passed expires_at; re-run get_products
• BUDGET_EXCEEDED: Operation would exceed allocated budget
• CREATIVE_REJECTED: Creative failed content-policy, brand-safety, or accessibility review
• CREATIVE_DEADLINE_EXCEEDED: Creative change submitted after the package’s creative_deadline
• INVALID_STATE: Operation is not permitted for the resource’s current status (e.g., updating a completed or canceled media buy)
• NOT_CANCELLABLE: Media buy or package cannot be canceled in its current state
• GOVERNANCE_DENIED: A registered governance agent denied the transaction. Buyer may restructure the buy, escalate to human spending authority, or contact the governance agent.
• TERMS_REJECTED: Buyer-proposed measurement_terms were rejected by the seller. Error details SHOULD identify which term failed and the seller’s acceptable range or supported vendors. Recovery: adjust the proposed terms and retry, or omit measurement_terms to accept the product’s defaults.
• BIDDING_PLACEMENT_CONFLICT: Media-buy/package bidding scopes cannot be represented by the provider’s native campaign, package, or shared-strategy placement. Sellers MUST reject before mutation and identify conflicting scopes where safe.
• AMBIGUOUS_BIDDING_POLICY: Canonical bidding and legacy bidding fields are both present on the same effective package. Sellers reject rather than choosing precedence.
• REQUOTE_REQUIRED: An update_media_buy request changes the parameter envelope (budget, flight dates, volume, targeting) the original quote was priced against. The pricing_option remains locked; the seller is declining the requested shape at that price. Distinct from TERMS_REJECTED (measurement) and POLICY_VIOLATION (content). Details SHOULD follow error-details/requote-required.json: envelope_field names the breached paths, change_term_id identifies the governing accepted right when present, and decline_reason SHOULD classify a structured seller-policy reason when the coarse dimension is safe to disclose. AdCP 3.2 buyers use the reason to inform refinement of accepted_proposal_id; some policies still require the buyer-safe message, a free-text ask, or human negotiation. Legacy 3.1 callers adjust the update, rediscover products or terms, add packages when available, or create a separate media buy.
• REFERENCE_DEFINITION_CHANGED: A third-party-published definition pinned in commercial_terms.definition_pins[] no longer resolves to the pinned content_digest. accept_proposal returns it before mutating state. Details SHOULD follow error-details/reference-definition-changed.json. Recovery: refine the proposal to obtain fresh pins, review the changed definition, and finalize again. See Definition pins.
• VALIDATION_ERROR: Request format or parameter errors
• AUTH_MISSING: No credentials were presented. Recovery: correctable.
• AUTH_INVALID: Credentials were presented but rejected (expired / revoked / malformed). Recovery: terminal.

​

Security Considerations

​

Transport Security

​

Authentication

• Orchestrators MUST authenticate with sales agents using valid credentials
• Sales agents MUST validate credentials before processing requests
• Sales agents MUST use account context to determine inventory access

​

Budget Authorization

• Sales agents MUST validate that accounts are authorized for requested budget levels
• Sales agents MUST NOT exceed authorized budget limits without explicit approval

​

Creative Security

• Sales agents MUST validate creative content for policy compliance
• Sales agents SHOULD scan creatives for malware and malicious content
• Sales agents MUST NOT serve creatives that fail security validation

​

Conformance

​

Sales Agent Conformance

1. Support at least one specified transport (MCP or A2A)
2. Implement all tasks per their schemas
3. Return required fields as defined in response schemas
4. Use specified error codes
5. Handle asynchronous operations appropriately
6. Enforce authentication and authorization
7. Apply get_products.targeting_overlay to product availability, pricing, and forecasts
8. Omit targeting_resolution for exact matches and disclose only modifications for configured alternatives
9. Treat placement, property, and collection selection as targeting and return complete effective package targeting on readback
10. Return dimension-specific execution details, including demographics, inside the generic package targeting_resolution envelope
11. For callers negotiating AdCP 3.3 or later, pin every covered third-party-published definition in commercial_terms.definition_pins[], verify the pins at finalize and before accept_proposal mutates state, and never accept request-authored pins

​

Orchestrator Conformance

1. Authenticate with sales agents
2. Include required fields as defined in request schemas
3. Handle asynchronous task-level responses (submitted, working, input-required) including webhook delivery of completion artifacts
4. Use media_buy_id to reference media buys in subsequent operations
5. Respect creative_deadline for creative uploads
6. Treat a selected context-scoped product_id as acceptance of its disclosed targeting_resolution

​

Implementation Notes

​

Response Time Expectations

​

Idempotency

• The same key and equivalent canonical payload within the replay window MUST return the original response without re-executing the request.
• The same key with a different canonical payload MUST return IDEMPOTENCY_CONFLICT.
• Keys are scoped to the authenticated caller and account so retries cannot cross tenant boundaries.

​

Human-in-the-Loop

• When the seller is waiting on an internal human (e.g. IO signing, traffic-manager review), sales agents MUST keep the task in status: "submitted" until the reviewer acts. On completion, the task transitions to completed with the final artifact carrying media_buy_id and the full success payload.
• When the seller needs the buyer to respond (e.g. confirm a budget that exceeds a pre-approved limit), sales agents MUST return status: "input-required" with a message describing what is needed. The buyer responds within the same A2A context.
• Sales agents SHOULD provide an estimated approval timeline in the task message.
• Orchestrators SHOULD implement webhook handlers (via push_notification_config) for completion notifications rather than polling.

​

Schema Reference