Skip to main content
control_media_buy applies operational changes that remain inside the immutable commercial envelope accepted for the MediaBuy. It requires the current revision for optimistic concurrency. Supported controls include:
  • pause, resume, and an already-permitted unilateral cancellation;
  • total, aggregate-daily, and package budget controls;
  • budget allocation, pacing, and bidding;
  • package targeting, catalog references, keyword, impression, and optimization controls; and
  • reporting-webhook configuration.
It does not accept creatives, creative assignments, new products/packages, flight-date changes, pricing changes, or billing-term changes. Those concerns use their dedicated lifecycle or a proposal refinement. Request schema: /schemas/3.0.24/media-buy/control-media-buy-request.json
Daily-cap changes apply immediately and atomically with spend already incurred in the current cap day counted. Lowering a cap below current-day spend pauses further applicable delivery without reversing prior spend. null removes an aggregate or package cap. A media-buy budget_cap_timezone change starts at the next boundary under the previously effective timezone; package controls never carry their own timezone. When an otherwise valid control would exceed the accepted budget, targeting, or delivery envelope, the seller returns REQUOTE_REQUIRED. The buyer reads accepted_proposal_id from get_media_buys, passes it to refine_proposals to create a draft amendment, finalizes that draft into a committed hold, and applies it through accept_proposal. This pointer survives SDK restart and moves atomically after each accepted amendment. A completed in-envelope control MAY include warnings[] for non-blocking observations, such as a material inventory shortfall forecast observed after the applied control. A continuing condition is also readable as an indicator through get_media_buys. Failed and submitted controls never carry this warning surface. Flight-date changes are not controls; a flight_change_creates_pacing_risk warning belongs on the completed accept_proposal response that applies the amendment. canceled: true is direct only when the accepted cancellation policy already grants the caller that right. A cancellation requiring counterparty agreement uses refine_proposals with change_kind: "cancellation". Seller-initiated cancellation does not call a buyer tool. The seller advances the MediaBuy revision and records cancellation.canceled_by: "seller"; get_media_buys is the normative recovery surface. A durable compact-lifecycle status-change webhook is intentionally not inferred from the per-operation async callback and remains 4.0 work.