AdCP refine_proposals Task

refine_proposals has two explicit operations over immutable proposal snapshots:

action: "revise" applies structured discovery criteria, typed boundaries, product changes, requested alternatives, and/or the buyer’s free-text ask, returning one or more new draft proposals.
action: "finalize" changes no commercial terms and returns a new committed proposal backed by an inventory hold until expires_at.

Revision may target a draft, committed, or accepted proposal; finalization must target a draft. A request contains at most 25 refinements. Proposal IDs must be unique within the request, and results preserve request order. Every successful operation returns a new proposal_id; that ID is the complete version identity for the immutable commercial snapshot, and the source remains unchanged. Request schema: /schemas/3.0.23/media-buy/refine-proposals-request.json

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655441002",
  "refinements": [
    {
      "proposal_id": "proposal_123",
      "action": "revise",
      "constraints": {
        "total_budget": { "max": 50000, "currency": "USD" },
        "cpm": { "max": 18, "currency": "USD" },
        "flight": { "end_no_earlier_than": "2026-10-31T23:59:59Z" }
      },
      "product_changes": {
        "premium_video": "include",
        "display_ros": "omit"
      },
      "alternatives": { "count": 3 },
      "ask": "Use materially different product mixes while preserving reach."
    },
    {
      "proposal_id": "proposal_456",
      "action": "revise",
      "criteria": {
        "targeting_overlay": {
          "geo_countries": ["US", "CA"]
        }
      }
    }
  ]
}

Typed fields are deliberately small and mechanically verifiable:

Field	Meaning
`constraints.total_budget`	Inclusive `min`/`max` bounds checked against a present `commercial_terms.total_budget`; `currency` must match and `min` must not exceed `max`. Each `constraints` key is its own stable constraint identifier.
`constraints.cpm`	Hard rate ceiling. Satisfied only when every purchase carries fixed `cpm`/`vcpm` pricing in the requested `currency` with `fixed_price` at or below `max`; auction-priced or non-CPM purchases leave it unsatisfied.
`constraints.impressions`	Hard volume floor. Satisfied only when every purchase carries `impressions` and their sum is at least `min`.
`constraints.flight`	Flight-window bounds. `start_no_later_than` requires a concrete `commercial_terms.start_time` at or before the bound (`asap` is unverifiable and unsatisfied); `end_no_earlier_than` requires `end_time` at or after it.
`product_changes`	Map keyed by product ID. `include` requires a product in `commercial_terms.purchases`; `omit` requires it to be absent. Keying makes contradictory actions unrepresentable.
`alternatives.count`	Number of drafts with distinct commercial terms requested, from 2 through the protocol maximum of 10 and no higher than a seller’s advertised `max_alternatives`. Returned alternatives have distinct `commercial_terms` and therefore unique `terms_digest` values; diversity strategy remains free text.
`criteria`	Structured discovery criteria to replace on the source proposal. Omitted criteria fields remain inherited; concrete targeting and offer filters belong here.
`ask`	Free text for substitution, trade-offs, diversity, preferences, or other long-tail context.

vary and typed preference enums are intentionally absent: concepts such as “prioritize reach” cannot be verified consistently against commercial_terms. A seller may interpret them from ask, but cannot report them as deterministically satisfied. Each present criteria field replaces that field from the source proposal; omitted fields remain bound to the revision. This makes a targeting change deterministic and ensures the revised proposal’s price and forecast use the new effective overlay. When hard targeting appears only in ask, the seller confirms any structured interpretation that materially affects the revision in that result’s targeting_resolution.brief_targeting. Exact structured targeting is not repeated; product-specific alternatives remain sparse modifications on the returned configured products. Response schema: /schemas/3.0.23/media-buy/refine-proposals-response.json The response contains one ordered results[] entry per requested source proposal. Each entry echoes source_proposal_id; buyers cross-check by that echo rather than by position alone. Every returned proposal carries parent_proposal_id equal to the entry’s source_proposal_id, so negotiation lineage survives in the proposals themselves:

Outcome	Proposal field	Meaning
`revised`	`proposals[]`	Every hard constraint is satisfied. Without `alternatives`, the array has one draft; with `alternatives.count`, it has exactly that many and every `terms_digest` is unique.
`partial`	`proposals[]`	Honest drafts were produced, but a hard constraint, typed change, requested count, or free-text ask was not fully applied. `reason_code` and `reason` are required.
`finalized`	`proposal`	One committed proposal backed by an inventory hold.
`unable`	none	No honest draft was produced. `reason_code` and `reason` are required.

reason_code distinguishes commercial refusal from implementation limits:

Code	Meaning
`commercially_declined`	The seller understood terms requested through the free-text `ask` but declined to offer them.
`constraint_unsatisfiable`	A typed constraint or product change was not satisfied — whether the seller cannot or will not meet it.
`unsupported_dimension`	The seller cannot parse or validate a requested typed dimension.
`uninterpreted`	Some or all of the free-text `ask` could not be interpreted.
`alternatives_unavailable`	Fewer distinct drafts were produced than requested.
`source_unavailable`	The source proposal was unavailable or ineligible for this caller.
`hold_unavailable`	The seller declined or failed to reserve inventory for a finalize.
`batch_aborted`	This entry failed only because a sibling in the all-or-none finalize batch failed.

Typed failures always use constraint_unsatisfiable, regardless of whether the refusal is capability or commercial; won’t-versus-can’t nuance belongs in reason or a commercially_declined response to an ask. When multiple shortfalls co-occur, constraint_unsatisfiable takes precedence over every other code, and an alternatives shortfall remains visible through proposals.length. A draft that violates a hard constraint MUST NOT be returned as revised. For constraints.total_budget, satisfaction requires a present commercial_terms.total_budget, the requested currency, and an amount inside every supplied bound. An absent total, currency mismatch, or out-of-range amount is unsatisfied: the seller returns partial, or unable when it cannot produce an honest draft, with reason_code: "constraint_unsatisfiable" and unsatisfied_constraints: ["total_budget"]. The other constraints keys behave identically under their satisfaction rules in the request schema. Every draft on a partial result MUST satisfy every typed constraint whose key is absent from unsatisfied_constraints and every product action absent from unsatisfied_product_changes, whatever the reason_code. This is the invariant that lets a buyer trust typed compliance without parsing prose. Constraint failures are identified through unsatisfied_constraints (echoing request constraints keys), unsatisfied_product_changes (a subset of the requested product-action map), or both. A partial response to the request above looks like:

{
  "adcp_version": "3.2.0",
  "status": "completed",
  "results": [
    {
      "source_proposal_id": "proposal_123",
      "outcome": "partial",
      "reason_code": "alternatives_unavailable",
      "reason": "Two commercially distinct packages are available at these terms.",
      "proposals": [
        { "proposal_id": "proposal_9a1", "parent_proposal_id": "proposal_123", "proposal_status": "draft", "...": "..." },
        { "proposal_id": "proposal_9a2", "parent_proposal_id": "proposal_123", "proposal_status": "draft", "...": "..." }
      ]
    },
    {
      "source_proposal_id": "proposal_456",
      "outcome": "revised",
      "proposals": [
        { "proposal_id": "proposal_9b7", "parent_proposal_id": "proposal_456", "proposal_status": "draft", "...": "..." }
      ]
    }
  ],
  "products": ["..."]
}

Every returned proposal carries typed commercial_terms and a terms_digest — the base64url SHA-256 of the RFC 8785 JCS serialization of commercial_terms, prefixed with sha256:. Buyers can and should recompute it: digest agreement, not seller assertion, is what makes drafts comparable and alternatives verifiably distinct. Only commercial_terms is contractual. Narrative fields — reason, suggestions, description, and anything a buyer wrote in ask — are explanatory and never part of the deal a later accept_proposal binds.

A realistic negotiation

Sam is buying a $50,000 Acme Outdoor campaign from StreamHaus. Capability discovery says StreamHaus supports total_budget, product_changes, alternatives, and criteria, with max_alternatives: 3. Sam can therefore construct one mechanically checkable request: cap spend at USD 50,000, include premium video, omit run-of-site display, narrow geography to the US and Canada, and ask for three distinct mixes. Suppose StreamHaus can satisfy the budget and targeting but can produce only two commercially distinct drafts. It returns partial with two proposals, reason_code: "alternatives_unavailable", and unique terms_digest values. Sam does not need to parse sales prose to understand the counteroffer: the typed budget and product checks still pass, while the requested alternative count does not. Sam can compare the two drafts, revise one again, or finalize the preferred draft. The failure paths are equally deterministic:

If a returned draft omits commercial_terms.total_budget, uses another currency, or exceeds the cap, the result identifies total_budget as unsatisfied and cannot be revised.
If Sam requests four alternatives against the advertised ceiling of three, the whole call fails with VALIDATION_ERROR at refinements[0].alternatives.count; StreamHaus creates no draft.
If StreamHaus omits criteria from supported_dimensions, the whole call fails with UNSUPPORTED_FEATURE before mutation. Sam can remove or translate that field and retry with a new valid payload.

This separation is the value of the compact negotiation surface: capabilities prevent impossible asks, typed fields make compliance testable, and ask remains available for the commercial nuance that cannot be reduced to a reliable boolean. Pass only a finalized committed proposal to accept_proposal, or use decline_proposals when the buyer stops pursuing it. The deprecated get_products buying_mode: "refine" surface is the 3.x compatibility façade; refine_proposals is the canonical compact-lifecycle negotiation task. The two surfaces share ask, product include/omit verbs, and the same budget_range {min,max,currency} shape — with inverted semantics. Legacy budget_range is a soft discovery filter the seller may miss without failing; compact constraints.total_budget is a hard constraint that forces partial or unable when violated. An adapter that copies the shape without converting the semantics silently turns a preference into a rejection. Compact hard constraints also reject unknown range members and require the semantic min <= max check; legacy filters remain extension-tolerant. The surfaces do not share response envelopes: legacy calls may return position-matched refinement_applied[], while compact calls return one results[] entry per source proposal and prohibit refinement_applied. Adapters may map a single legacy proposal refinement into the compact task, but must not invent support for per-proposal constraints or alternatives that the legacy envelope cannot represent faithfully. The legacy more_like_this verb has no typed compact equivalent and maps only lossily into ask.

Finalize and hold inventory

Finalization is seller commitment, not buyer acceptance. It locks the already-negotiated terms and reserves inventory until the returned expires_at:

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655441003",
  "refinements": [
    {
      "proposal_id": "proposal_draft_789",
      "action": "finalize"
    }
  ]
}

A request containing finalize must contain only finalize entries. Sellers validate the complete batch before creating any holds; multi-proposal finalization is atomic. When any hold cannot be created, no result is finalized: the failing entry returns unable with reason_code: "hold_unavailable", and otherwise-eligible siblings return unable with reason_code: "batch_aborted". Exact retries use the same idempotency key. A new key does not extend or recreate an existing hold: while a committed successor’s hold is unexpired, finalizing the same draft again MUST fail at task level with INVALID_STATE rather than minting a second hold; after expiry a new finalize MAY create a new one. Holds are a seller commitment against real inventory, so hold policy is the seller’s. Sellers MAY decline any hold (hold_unavailable), MAY cap concurrent unexpired holds per buyer to prevent inventory squatting, and choose expires_at themselves — the hold window should be long enough to complete acceptance and short enough that unaccepted holds do not function as free inventory options. Nothing in this task obliges a seller to grant holds without whatever credit or relationship checks it applies to reservations generally; the async submitted path exists for exactly that re-underwriting. Every revised proposal inherits the source proposal’s opportunity association. Callers do not repeat opportunity context during refinement.

Negotiation security

Both sides of this task are agents, and both sides’ inputs are untrusted. ask is attacker-controlled free text: sellers MUST NOT let it alter pricing floors, authorization, or policy, and MUST NOT expose other buyers’ terms through it — fence it from any LLM with pricing authority and treat its interpretation as suggestion, never instruction. In the other direction, deterministic constraint_unsatisfiable responses form a price oracle: repeated budget or rate probes can binary-search a floor at no cost. Sellers SHOULD apply rate or commercial friction to sustained un-held revision rounds and MAY keep reason deliberately coarse rather than revealing how near a rejected constraint came to clearing.

Amend an accepted MediaBuy

An accepted proposal is the immutable commercial envelope attached to its MediaBuy. Refining it forks a successor proposal rather than reopening or mutating the accepted snapshot:

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655441013",
  "refinements": [
    {
      "proposal_id": "proposal_accepted_123",
      "action": "revise",
      "change_kind": "amendment",
      "ask": "Extend the flight by two weeks and add the premium video product."
    }
  ]
}

Use change_kind: "cancellation" when cancellation requires counterparty agreement. The returned draft has proposal_kind: "media_buy_cancellation", identifies the MediaBuy and base revision, and must be finalized before it can be applied through accept_proposal. Sellers MAY respond asynchronously with status: "submitted" when a complex multi-publisher revision or inventory hold requires upstream pricing queries or manual re-underwriting. In that case the response contains a task_id for polling via get_task_status; terminal results are delivered on the completion artifact or via push notification if push_notification_config was supplied.

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

refine_proposals

A realistic negotiation

Relationship to legacy refinement

Finalize and hold inventory

Negotiation security

Amend an accepted MediaBuy

​A realistic negotiation

​Relationship to legacy refinement

​Finalize and hold inventory

​Negotiation security

​Amend an accepted MediaBuy

A realistic negotiation

Relationship to legacy refinement

Finalize and hold inventory

Negotiation security

Amend an accepted MediaBuy