Optionalname?: stringPersisted human-readable name after the update. When update_media_buy supplied name, the seller MUST return the stored value here; a seller that could not apply the replacement SHOULD return the prior unchanged value rather than silently dropping the field. This display label is not an identifier or financial reference.
Optionalmedia_buy_status?: MediaBuyStatusOptionalrevision?: numberRevision number after this update. Use this value in subsequent update_media_buy requests intended to change state for optimistic concurrency. Exact idempotency replays return the prior revision and do not increment revision.
Optionalcurrency?: stringISO 4217 currency code for monetary values at this media buy level. Echoed when the update affects budget or currency. Matches the currency field in subsequent get_media_buys responses.
Optionaltotal_budget?: numberUpdated hard aggregate lifetime budget, denominated in currency. Echoed when the update affects the shared total or package budgets so buyers can verify the new aggregate without a round-trip to get_media_buys.
Optionaldaily_budget_cap?: numberPost-update hard aggregate daily spend ceiling. Echoed when the update sets or changes the aggregate daily cap; omitted after the cap is removed.
Optionalbudget_cap_timezone?: stringPost-update IANA timezone shared by every aggregate and package daily cap. Echoed whenever the update affects daily caps or their timezone.
Optionalbudget_allocation?: Post-update cross-package allocation configuration when affected by the update.
Optionalpacing?: PacingOptionalbidding?: {Post-update media-buy-authored bidding policy when affected by the update, preserving explicit automatic mode, scope-specific goal binding, and media-buy-currency denomination. Omitted when the authored media-buy block was cleared.
Optionalautomatic?: trueExplicitly use seller/provider automatic bidding at this authored scope. At package scope this is a complete override of a media-buy policy, not inheritance. It MUST be the only field in the block and MUST be preserved on readback.
Optionalbid_amount?: numberManual auction bid denominated in the media-buy currency and expressed per the selected pricing option's auction unit. For example, a CPM option interprets the amount per thousand impressions. This is the amount submitted to the auction, not a promise that the clearing price equals it. Requires an auction-priced pricing option whose currency equals the media-buy currency.
Optionalmax_bid?: numberHard per-auction ceiling denominated in the media-buy currency and expressed per the selected pricing option's auction unit. This is the only canonical hard auction ceiling and MUST NOT be translated into an average outcome-cost control. Requires an auction-priced pricing option whose currency equals the media-buy currency. May stand alone or supplement cost_per/roas only when the relevant scope capability advertises that combination.
Optionalcost_per?: { amount: number; strength: "cap" | "target" }Average cost control per result of the scope-bound primary optimization goal. At seller-optimized media-buy scope it binds to budget_allocation.optimization_goals; at package scope it binds to that package's optimization_goals; at fixed media-buy scope it binds independently to each inheriting package and is valid only when their primary-goal result units are compatible. Metric goals are compatible only when metric and every result-defining qualifier match; vendor_metric goals only when vendor and metric_id match; event goals only when the event_type/custom_event_name set and resolved attribution_window match. Primary is the earliest array entry among goals tied for the lowest explicit numeric priority; unprioritized goals follow explicitly prioritized goals; when all priorities are absent, the first entry is primary.
Average cost amount per scope-bound primary-goal result, denominated in the media-buy currency.
cap optimizes for an average at or below the amount and accepts underdelivery when necessary; target optimizes around the amount while balancing volume and spend. Neither is a per-result or per-auction guarantee.
Optionalroas?: { value: number; strength: "target" | "floor" }Dimensionless return-on-ad-spend control bound to the same scope-specific primary goal rules as cost_per. The bound goal must be value-bearing; a fixed media-buy default requires a value-bearing primary goal on every inheriting package. Every referenced value-bearing event source MUST declare value_currencies containing the media-buy currency. The seller validates this at buy creation; each buy consumes only exact-currency records, while other declared currencies remain available to other buys. Sellers MUST NOT perform currency conversion.
Return per unit of ad spend; 4 means 4 units of value per 1 unit spent.
floor prefers underdelivery to knowingly optimizing below the requested return; target optimizes around the requested return. Neither guarantees realized return.
Optionalimplementation_date?: string | nullISO 8601 timestamp when changes take effect (null if pending approval)
Optionalinvoice_recipient?: Omit<Optionalaffected_packages?: {Array of full Package objects showing complete post-update state for each modified package. This includes every active package whose budget was proportionally changed by a fixed-mode total_budget update. This is a state snapshot, not a sparse delta: sellers MUST NOT return package_id-only stubs. Campaign-level updates that do not modify packages may return an empty array.
Optionalvalid_actions?: MediaBuyValidAction[]Flat-vocabulary actions the buyer can perform after this update. Saves a round-trip to get_media_buys. Deprecated in favor of available_actions[], which carries mode, optional SLA, and optional terms_ref. Sellers SHOULD populate both during the 3.x deprecation window; consumers MUST prefer available_actions[] when both are present. Removed in 4.0.
Optionalavailable_actions?: {Structured per-buy resolution of actions available after this update. Authoritative — see get-media-buys-response.json for full semantics.
Optionalwarnings?: {Optional non-blocking observations accompanying this successful update. The requested update was still applied. Continuing conditions also appear on get_media_buys as current resource state.
Optionalsandbox?: booleanWhen true, this response contains simulated data from sandbox mode.
Optionalcontext?: Omit<Omit<{}, "bank">, "authentication"> & { authentication?: unknown }Optionalext?: Omit<Omit<{ [key: string]: unknown }, "bank">, "authentication"> & {Optionalsummary: string
Seller's identifier for the media buy