completed、120 秒未満の working、または手動審査用の submitted)
スコープ
update_media_buy は、create_media_buy で作成された購入だけでなく、get_media_buys が返す任意の media_buy_id に対して動作します。セラーエージェントは、購入が元々 AdCP の外(アドサーバーへの直接入力、レガシー API、手動トラフィッキング)で作成されたことを理由に更新を拒否してはなりません(MUST NOT)。作成サーフェスは認可の軸としてサポートされていません。アカウントの所有権がその軸です。
ビジネス上の理由(契約上の義務、プラットフォームの制約、ポリシー)により特定のアクションが特定の購入でサポートされない場合、セラーは対応する更新を暗黙に拒否するのではなく、その購入の valid_actions(および available_actions[] の対応エントリ)からそのアクションのみを省略しなければなりません(MUST)。作成サーフェスはビジネス上の理由ではありません。 セラーは、AdCP 外で作成された購入に対するその他の点で有効な更新に INVALID_STATE を返してはならず(MUST NOT)、AdCP 外で予約されたという理由だけで valid_actions が体系的に空の購入を返してはなりません(MUST NOT)——そのパターンは購入を隠すことと区別できず、アカウント所有権 vs 作成サーフェスのルールに違反します。
アクション語彙とフィールドマッピング
バイヤーはアクションを通じて意図を表現します。セラーは、構造化されたavailable_actions[] フィールド(権威的)と、フラットな valid_actions[] フィールド(レガシー、4.0 で非推奨)を通じて、各購入で利用可能なアクションを宣言します。両フィールドが存在する場合、コンシューマーは available_actions[] を優先しなければなりません(MUST)——それは、フラットな文字列配列が表現できない解決済みの mode、任意の sla、任意の terms_ref を運びます。バイヤーが update_media_buy リクエストを発行すると、セラーはリクエストのフィールドを一つ以上のアクションにマップし、マップされたアクションが購入の解決済み available_actions[] にない場合は ACTION_NOT_ALLOWED(error.details に attempted_action、reason、currently_available_actions を伴う)で拒否します。
このマッピングは規範的です——セラーと SDK は、実装をまたいでサーフェスが一貫するよう、リクエストフィールドとアクション識別子の変換にこの表を使わなければなりません(MUST)。
変化の方向を表すアクション(
extend_flight / shorten_flight、increase_budget / decrease_budget / reallocate_budget)は update_fields のパスを共有します。アクションは、どのフィールドが設定されたかではなく、要求値を購入の現在状態と比較して決まります。サーバー側のディスパッチ強制は、正しいアクションを選ぶためにリクエストと現在状態を差分しなければならず(MUST)、解決されたアクションが購入の available_actions[] にない場合は ACTION_NOT_ALLOWED で拒否しなければなりません。
| update_targeting | packages[].targeting_overlay, packages[].keyword_targets_add, packages[].keyword_targets_remove, packages[].negative_keywords_add, packages[].negative_keywords_remove | |
| update_pacing | packages[].pacing | |
| update_frequency_caps | packages[].targeting_overlay.frequency_cap | 他のターゲティングよりフライト中に再交渉されることが多い。フィールドは複数形ではなく単数の frequency_cap(単一ルール)。 |
| replace_creative | packages[].creatives[] の入れ替え(割り当ては不変) | 割り当てセットの変更とは別の AM ワークフロー |
| update_creative_assignments | packages[].creative_assignments | どのクリエイティブをどこに |
| remove_creative | 置換ペイロードの packages[].creatives[] および/または packages[].creative_assignments からクリエイティブを省略 | 両配列は置換セマンティクスを使うため、削除は目的の事後状態をクリエイティブ不在で送ることで表現します(3.x に明示的な削除プリミティブはありません)。時間に敏感であり、追加/入れ替えに承認が必要な場合でも、セラーは self_serve の削除をサポートすべきです(SHOULD) |
| add_packages | new_packages[] | |
| remove_packages | packages[].canceled: true | |
粗いレガシーアクション(update_budget、update_dates、update_packages、sync_creatives)は、3.0 の列挙サーフェスをまだ出しているセラー向けに、より細かい語彙を単一の値でカバーします。セラーはより細かいセットへ移行すべきです(SHOULD)。レガシー値は 4.0 で削除されます。
アクションモード
available_actions[] の各エントリは、単数の mode(購入の現在状態に対して解決済み)を運びます。プロダクトレベルの allowed_actions[] テンプレートでは、プロダクトが複数の条件付きモードを提供しうる(例: 許容範囲内は self_serve、範囲外は requires_approval へエスカレーション)ため、フィールドは複数形の modes[] です。
バイヤー SDK は、同期レスポンス・条件付き処理・非同期の承認コールバックのどれを期待するかを決めるため、
mode で分岐しなければなりません(MUST)。リクオートは 3.1 ではアクションモードとしてモデル化されていません。要求された更新が現在の見積もりの範囲を超える場合、セラーは REQUOTE_REQUIRED を返します。
PATCH セマンティクス: 指定したフィールドのみ更新し、未指定フィールドは変更しません。
Request Schema: /schemas/v3/media-buy/update-media-buy-request.json
Response Schema: /schemas/v3/media-buy/update-media-buy-response.json
クイックスタート
メディアバイを作成し、一時停止します。リクエストパラメーター
account と media_buy_id は常に必須です。
楽観的並行制御
revision は想定される現在のメディアバイのリビジョンです。一部の実装は内部的にこの値を expected_revision と呼びますが、AdCP のワイヤー上のフィールドは revision です。後方互換のためこのフィールドは任意です。存在する場合、セラーは変更を伴う更新を適用する書き込みとアトミックにこれをチェックしなければなりません(MUST)。アプリケーションコードで現在値を読み、比較し、後で書き込むと、別のライターと競合して更新を失う可能性があります。保存されたリビジョンがリクエストの revision と異なる場合、セラーは CONFLICT で拒否し、変更を一切適用しません。
変更を伴うすべての更新は revision をインクリメントし、成功レスポンスで新しい値を返します。検証のみのリクエスト、読み取り、厳密な冪等リプレイはインクリメントしません。厳密なリプレイは以前のリビジョンを返します。クライアントは、状態変更を意図するすべての更新で最後に観測したリビジョンを渡し、CONFLICT を受け取ったら get_media_buys で再読み込みして新しい idempotency_key でリトライすべきです(SHOULD)。
Reporting Webhook オブジェクト
このメディアバイの自動レポート配信を設定します。
Note:
reporting_webhook はキャンペーンの継続レポート設定、push_notification_config は「この更新が完了したら知らせて」といった非同期通知用です。
Package Update オブジェクト
package_id は更新対象のパッケージを識別するために必須です。
レスポンス
成功レスポンス
エラーレスポンス
Note: レスポンスは判別可能なユニオン。成功フィールドか errors のどちらかのみ返されるため、成功フィールドにアクセスする前に
errors を確認してください。
主なシナリオ
パッケージ予算の更新
特定パッケージの予算を増額:キャンペーン日程の変更
キャンペーン終了日を延長:ターゲティングの更新
地理制限を追加・変更:Replace Creatives
Swap out creative assignments for a package:Multiple Package Updates
Update multiple packages in one call:メディアバイのキャンセル
メディアバイ全体をキャンセルします:media_buy_status が、購入のライフサイクル状態に関する 3.1 の正準フィールドです。レガシーのトップレベル status: MediaBuyStatus 形式(例: "status": "canceled")は非推奨で、3.2 で削除されます(#4906)——それは同じルートキーでエンベロープのタスクステータスと衝突していました。移行については移行 › media_buy_statusを参照してください。
NOT_CANCELLABLE エラーレスポンス:
INVALID_STATE エラーレスポンス(例: 完了したメディアバイを更新しようとした場合):
REQUOTE_REQUIRED エラーレスポンス(更新が、見積もりの価格算定基準となったパラメータの範囲を変える場合):
パッケージのキャンセル
メディアバイをアクティブなまま、単一のパッケージをキャンセルします:What Can Be Updated
Campaign-Level Updates
✅ Can update:- Start/end times (subject to seller approval)
- Campaign status (active/paused/canceled)
- Reporting webhook configuration (URL, frequency, metrics)
- Media buy ID
- Brand reference
- Original package product IDs
Package-Level Updates
✅ Can update:- Budget allocation
- Pacing strategy
- Bid prices (auction products)
- Optimization goal (event source, event type, target ROAS/CPA)
- Targeting overlays
- Creative assignments
- Package status (active/paused/canceled)
- Catalog reference (replace the catalog a catalog-driven package promotes)
- Creative assignments (before the package’s
creative_deadline)
not constraint on package-update.json):
- Package ID
- Product ID
- Pricing option ID
- Format selectors:
format_ids,format_option_refs,format_kind, andparams(creatives must match existing formats)
committed_metrics— セラーは新しいエントリ(フライト中のメトリクス追加。それぞれ独自のcommitted_atタイムスタンプを持つ)を受け入れますが、既存エントリを変更または削除しようとする試みをvalidation_error(コードIMMUTABLE_FIELD)で拒否しなければなりません(MUST)。ランタイムでの強制です。追記専用のセマンティクスはスキーマのnot節では表現できません。
Error Handling
Common errors and resolutions:
Example error response:
Update Approval
Some updates require seller approval and return pending status:- Significant budget increases (threshold varies by seller)
- Date range changes affecting inventory availability
- Targeting changes that alter campaign scope
- Creative changes requiring policy review
implementation_date will be null:
PATCH Semantics
Only specified fields are updated - omitted fields remain unchanged:creative_assignments), provide the complete new array:
Asynchronous Operations
Updates may be asynchronous, especially with seller approval.Response Patterns
Synchronous (completed immediately):Protocol-Specific Handling
AdCP tasks work across multiple protocols (MCP, A2A, REST). Each protocol handles async operations differently:- Status checking: Polling, webhooks, or streaming
- Updates: Protocol-specific mechanisms
- Long-running tasks: Different timeout and notification patterns
Best Practices
1. Use Precise Updates Update only what needs to change - don’t resend unchanged values. 2. Budget Increases Small incremental increases are more likely to be auto-approved than large jumps. 3. Pause Before Major Changes Pause campaigns before making significant targeting or creative changes to avoid delivery issues. 4. Test with Small Changes Test update workflows with minor changes before critical campaign modifications. 5. Monitor Status Always check response status andimplementation_date for approval requirements.
6. Validate Package State
Check affected_packages in response to confirm changes were applied correctly.
Usage Notes
- Updates are atomic - either all changes apply or none do
- Both media buys and packages can be referenced by publisher IDs
- Pending states (
working,submitted) are normal, not errors - Orchestrators MUST handle pending states as part of normal workflow
implementation_dateindicates when changes take effect (null if pending approval)- Inline creatives:
creatives配列はパッケージのインラインクリエイティブ本体を置き換えます。セラーがcreative.has_creative_library: trueを宣言する場合、既存のライブラリクリエイティブを更新するにはsync_creativesを、既存のライブラリクリエイティブを割り当てるにはcreative_assignmentsを使用します。セラーがクリエイティブライブラリなしでinline_creative_management: trueを宣言する場合、インラインクリエイティブの追加・置換・削除のワークフローにはここのpackages[].creativesを使用します。
キャンペーンガバナンス — 変更フェーズバイヤーのアカウントにガバナンスエージェントが設定されている場合、セラーは更新を確定する前に、
media_buy_id、planned_delivery、phase: "modification" を伴って check_governance を呼び出さなければなりません(MUST)。ガバナンスエージェントは、変更の大きさ、予算の再配分、新しいパラメータをキャンペーンプランに対して検証します。完全な実行チェックのワークフローとコード例はセラー統合ガイドを参照してください。Next Steps
After updating a media buy:- Verify Changes: Use
get_media_buy_deliveryto confirm updates - Upload New Creatives: Use
sync_creativesif creative assignments changed - Monitor Performance: Track impact of changes on campaign metrics
- Optimize Further: Use
provide_performance_feedbackfor ongoing optimization
Learn More
- Media Buy Lifecycle - Complete campaign workflow
- Targeting - Targeting overlays and restrictions
- Async Operations - Async patterns and status checking
- create_media_buy - Initial campaign creation