update_media_buy

既存のメディアバイを PATCH セマンティクスで更新します。キャンペーン全体およびパッケージ単位の更新をサポートします。 Response Time: 即時〜日単位（completed、120 秒未満の working、または手動審査用の submitted） PATCH セマンティクス: 指定したフィールドのみ更新し、未指定フィールドは変更しません。 Request Schema: /schemas/v2/media-buy/update-media-buy-request.json Response Schema: /schemas/v2/media-buy/update-media-buy-response.json

クイックスタート

メディアバイを作成し、一時停止します。

import { testAgent } from '@adcp/client/testing';
import { CreateMediaBuyResponseSchema, UpdateMediaBuyResponseSchema } from '@adcp/client';

// まず更新対象のメディアバイを作成
const uniqueRef = `test_campaign_${Date.now()}`;

// 開始/終了日は未来の日付を使用
const startDate = new Date();
startDate.setDate(startDate.getDate() + 7); // Start 1 week from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 37); // End 5 weeks from now

const createResult = await testAgent.createMediaBuy({
  buyer_ref: uniqueRef,
  brand_manifest: {
    name: 'Nike',
    url: 'https://nike.com'
  },
  packages: [{
    buyer_ref: 'display_pkg',
    product_id: 'prod_d979b543',
    pricing_option_id: 'cpm_usd_fixed',
    format_ids: [{
      agent_url: 'https://creative.adcontextprotocol.org',
      id: 'display_300x250_image'
    }],
    budget: 800,
    bid_price: 5.00
  }],
  start_time: startDate.toISOString(),
  end_time: endDate.toISOString()
});

if (!createResult.success) {
  throw new Error(`Create failed: ${createResult.error}`);
}

const created = CreateMediaBuyResponseSchema.parse(createResult.data);
if ('errors' in created && created.errors) {
  throw new Error(`Create failed: ${JSON.stringify(created.errors)}`);
}

console.log(`Created media buy ${created.media_buy_id}`);

// 続いてキャンペーンを一時停止
const updateResult = await testAgent.updateMediaBuy({
  buyer_ref: uniqueRef,
  paused: true
});

if (!updateResult.success) {
  throw new Error(`Update failed: ${updateResult.error}`);
}

const updated = UpdateMediaBuyResponseSchema.parse(updateResult.data);
if ('errors' in updated && updated.errors) {
  throw new Error(`Update failed: ${JSON.stringify(updated.errors)}`);
}

console.log(`Campaign ${updated.media_buy_id} paused`);

リクエストパラメーター

Parameter	Type	Required	Description
`media_buy_id`	string	Yes*	更新対象のパブリッシャー側メディアバイ ID
`buyer_ref`	string	Yes*	更新対象のバイヤー参照 ID
`start_time`	string	No	更新後の開始日時
`end_time`	string	No	更新後の終了日時
`paused`	boolean	No	メディアバイ全体を一時停止/再開（`true`=停止、`false`=稼働）
`packages`	PackageUpdate[]	No	パッケージ単位の更新（下記参照）
`reporting_webhook`	object	No	レポート用 Webhook 設定の更新（下記参照）
`push_notification_config`	object	No	非同期処理通知用 Webhook

*Either media_buy_id OR buyer_ref is required (not both)

Reporting Webhook オブジェクト

このメディアバイの自動レポート配信を設定します。

Parameter	Type	Required	Description
`url`	string	Yes	Webhook エンドポイント URL
`authentication`	object	Yes	`schemes` と `credentials` を持つ認証設定
`reporting_frequency`	string	Yes	`hourly` / `daily` / `monthly`
`requested_metrics`	string[]	No	取得したい指標（未指定ならすべて）
`token`	string	No	検証用のクライアントトークン（16 文字以上）

Note: reporting_webhook はキャンペーンの継続レポート設定、push_notification_config は「この更新が完了したら知らせて」といった非同期通知用です。

Package Update オブジェクト

Parameter	Type	Description
`package_id`	string	更新対象のパブリッシャー側パッケージ ID
`buyer_ref`	string	更新対象のバイヤー参照 ID
`paused`	boolean	パッケージ単位で一時停止/再開（`true`=停止、`false`=稼働）
`budget`	number	予算の更新値
`impressions`	number	このパッケージのインプレッション目標の更新値
`pacing`	string	ペーシング戦略の更新
`bid_price`	number	入札額の更新（オークション商品のみ）
`targeting_overlay`	TargetingOverlay	ターゲティング制約の更新
`creative_assignments`	CreativeAssignment[]	割り当てクリエイティブを置き換え（重み/プレースメント指定可）
`creatives`	CreativeAsset[]	新規クリエイティブをインラインでアップロード・割り当て（ライブラリ未登録であること）

*各パッケージ更新では package_id または buyer_ref のどちらかが必須

レスポンス

成功レスポンス

Field	Description
`media_buy_id`	メディアバイ ID
`buyer_ref`	バイヤー参照 ID
`implementation_date`	変更が反映される日時 (ISO 8601)。承認待ちの場合は null
`affected_packages`	更新後の完全な状態を示す Package オブジェクト配列

エラーレスポンス

Field	Description
`errors`	Array of error objects explaining failure

Note: レスポンスは判別可能なユニオン。成功フィールドか errors のどちらかのみ返されるため、成功フィールドにアクセスする前に errors を確認してください。

主なシナリオ

パッケージ予算の更新

特定パッケージの予算を増額:

import { testAgent } from '@adcp/client/testing';
import { UpdateMediaBuyResponseSchema } from '@adcp/client';

const result = await testAgent.updateMediaBuy({
  media_buy_id: 'mb_12345',
  packages: [{
    buyer_ref: 'ctv_package',
    budget: 50000  // Increased from 30000
  }]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = UpdateMediaBuyResponseSchema.parse(result.data);

if ('errors' in validated && validated.errors) {
  throw new Error(`Update failed: ${JSON.stringify(validated.errors)}`);
}

const pkg = validated.affected_packages?.find(p => p.buyer_ref === 'ctv_package');
if (pkg) {
  console.log(`Package budget updated to ${pkg.budget}`);
}

キャンペーン日程の変更

キャンペーン終了日を延長:

import { testAgent } from '@adcp/client/testing';
import { UpdateMediaBuyResponseSchema } from '@adcp/client';

const result = await testAgent.updateMediaBuy({
  buyer_ref: 'summer_campaign_2025',
  end_time: '2025-09-30T23:59:59Z'
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = UpdateMediaBuyResponseSchema.parse(result.data);

if ('errors' in validated && validated.errors) {
  throw new Error(`Update failed: ${JSON.stringify(validated.errors)}`);
}

console.log('Campaign end date extended');
console.log(`Effective: ${validated.implementation_date}`);

ターゲティングの更新

地理制限を追加・変更:

import { testAgent } from '@adcp/client/testing';
import { UpdateMediaBuyResponseSchema } from '@adcp/client';

const result = await testAgent.updateMediaBuy({
  media_buy_id: 'mb_12345',
  packages: [{
    buyer_ref: 'ctv_package',
    targeting_overlay: {
      geo_country_any_of: ['US', 'CA'],
      geo_region_any_of: ['CA', 'NY', 'TX', 'ON', 'QC']
    }
  }]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = UpdateMediaBuyResponseSchema.parse(result.data);

if ('errors' in validated && validated.errors) {
  throw new Error(`Update failed: ${JSON.stringify(validated.errors)}`);
}

console.log('Targeting updated successfully');

Replace Creatives

Swap out creative assignments for a package:

import { testAgent } from '@adcp/client/testing';
import { UpdateMediaBuyResponseSchema } from '@adcp/client';

const result = await testAgent.updateMediaBuy({
  media_buy_id: 'mb_12345',
  packages: [{
    buyer_ref: 'ctv_package',
    creative_assignments: [
      { creative_id: 'creative_video_v2' },
      { creative_id: 'creative_display_v2', weight: 60 }
    ]
  }]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = UpdateMediaBuyResponseSchema.parse(result.data);

if ('errors' in validated && validated.errors) {
  throw new Error(`Update failed: ${JSON.stringify(validated.errors)}`);
}

const pkg = validated.affected_packages?.find(p => p.buyer_ref === 'ctv_package');
const assignmentCount = pkg?.creative_assignments?.length || 0;
console.log(`Assigned ${assignmentCount} creatives`);

Multiple Package Updates

Update multiple packages in one call:

import { testAgent } from '@adcp/client/testing';
import { UpdateMediaBuyResponseSchema } from '@adcp/client';

const result = await testAgent.updateMediaBuy({
  media_buy_id: 'mb_12345',
  packages: [
    {
      buyer_ref: 'ctv_package',
      budget: 50000,
      pacing: 'front_loaded'
    },
    {
      buyer_ref: 'audio_package',
      budget: 30000,
      paused: true
    }
  ]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = UpdateMediaBuyResponseSchema.parse(result.data);

if ('errors' in validated && validated.errors) {
  throw new Error(`Update failed: ${JSON.stringify(validated.errors)}`);
}

console.log(`Updated ${validated.affected_packages?.length || 0} packages`);

What Can Be Updated

Campaign-Level Updates

✅ Can update:

Start/end times (subject to seller approval)
Campaign status (active/paused)
Reporting webhook configuration (URL, frequency, metrics)

❌ Cannot update:

Media buy ID
Buyer reference
Brand manifest
Original package product IDs

Package-Level Updates

✅ Can update:

Budget allocation
Pacing strategy
Bid prices (auction products)
Targeting overlays
Creative assignments
Package status (active/paused)

❌ Cannot update:

Package ID
Product ID
Pricing option ID
Format IDs (creatives must match existing formats)

Error Handling

Common errors and resolutions:

Error Code	Description	Resolution
`MEDIA_BUY_NOT_FOUND`	Media buy doesn’t exist	Verify media_buy_id or buyer_ref
`PACKAGE_NOT_FOUND`	Package doesn’t exist	Verify package_id or buyer_ref
`UPDATE_NOT_ALLOWED`	Field cannot be changed	See “What Can Be Updated” above
`BUDGET_INSUFFICIENT`	New budget below minimum	Increase budget amount
`POLICY_VIOLATION`	Update violates content policy	Review policy requirements
`INVALID_STATE`	Operation not allowed in current state	Check campaign status
`CREATIVE_ID_EXISTS`	Creative ID already exists in library	Use a different `creative_id`, assign existing creatives via `creative_assignments`, or update via `sync_creatives`

Example error response:

{
  "errors": [{
    "code": "UPDATE_NOT_ALLOWED",
    "message": "Cannot change product_id for existing package",
    "field": "packages[0].product_id",
    "suggestion": "Create a new package with the desired product instead"
  }]
}

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

When approval is needed, implementation_date will be null:

{
  "media_buy_id": "mb_12345",
  "buyer_ref": "summer_campaign_2025",
  "implementation_date": null,
  "affected_packages": []
}

PATCH Semantics

Only specified fields are updated - omitted fields remain unchanged:

{
  "buyer_ref": "summer_campaign_2025",
  "packages": [{
    "buyer_ref": "ctv_package",
    "budget": 50000
  }]
}

Array replacement: When updating arrays (like creative_assignments), provide the complete new array:

{
  "packages": [{
    "buyer_ref": "ctv_package",
    "creative_assignments": [
      { "creative_id": "creative_video_v2" },
      { "creative_id": "creative_display_v2", "weight": 60 }
    ]
  }]
}

Asynchronous Operations

Updates may be asynchronous, especially with seller approval.

Response Patterns

Synchronous (completed immediately):

{
  "media_buy_id": "mb_12345",
  "buyer_ref": "summer_campaign_2025",
  "implementation_date": "2025-06-15T10:00:00Z",
  "affected_packages": []
}

Asynchronous (processing):

{
  "status": "working",
  "message": "Processing update..."
}

Poll for completion or use webhooks/streaming. Manual Approval Required:

{
  "status": "submitted",
  "message": "Update requires seller approval (2-4 hours)"
}

Will take hours to days.

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

See Async Operations for protocol-specific async patterns and examples.

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 and implementation_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 buyer_ref or publisher IDs
Pending states (working, submitted) are normal, not errors
Orchestrators MUST handle pending states as part of normal workflow
implementation_date indicates when changes take effect (null if pending approval)
Inline creatives: The creatives array creates NEW creatives only. To update existing creatives, use sync_creatives. To assign existing library creatives, use creative_assignments in the Package Update object.

Next Steps

After updating a media buy:

Verify Changes: Use get_media_buy_delivery to confirm updates
Upload New Creatives: Use sync_creatives if creative assignments changed
Monitor Performance: Track impact of changes on campaign metrics
Optimize Further: Use provide_performance_feedback for 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

Getting Started

Building with AdCP

Governance Protocol

Signals Protocol

Curation Protocol

Sponsored Intelligence Protocol

Media Buy Protocol

Creative

Reference

Community

クイックスタート

リクエストパラメーター

Reporting Webhook オブジェクト

Package Update オブジェクト

レスポンス

成功レスポンス

エラーレスポンス

主なシナリオ

パッケージ予算の更新

キャンペーン日程の変更

ターゲティングの更新

Replace Creatives

Multiple Package Updates

What Can Be Updated

Campaign-Level Updates

Package-Level Updates

Error Handling

Update Approval

PATCH Semantics

Asynchronous Operations

Response Patterns

Protocol-Specific Handling

Best Practices

Usage Notes

Next Steps

Learn More

Getting Started

Building with AdCP

Governance Protocol

Signals Protocol

Curation Protocol

Sponsored Intelligence Protocol

Media Buy Protocol

Creative

Reference

Community

​クイックスタート

​リクエストパラメーター

​Reporting Webhook オブジェクト

​Package Update オブジェクト

​レスポンス

​成功レスポンス

​エラーレスポンス

​主なシナリオ

​パッケージ予算の更新

​キャンペーン日程の変更

​ターゲティングの更新

​Replace Creatives

​Multiple Package Updates

​What Can Be Updated

​Campaign-Level Updates

​Package-Level Updates

​Error Handling

​Update Approval

​PATCH Semantics

​Asynchronous Operations

​Response Patterns

​Protocol-Specific Handling

​Best Practices

​Usage Notes

​Next Steps

​Learn More

クイックスタート

リクエストパラメーター

Reporting Webhook オブジェクト

Package Update オブジェクト

レスポンス

成功レスポンス

エラーレスポンス

主なシナリオ

パッケージ予算の更新

キャンペーン日程の変更

ターゲティングの更新

Replace Creatives

Multiple Package Updates

What Can Be Updated

Campaign-Level Updates

Package-Level Updates

Error Handling

Update Approval

PATCH Semantics

Asynchronous Operations

Response Patterns

Protocol-Specific Handling

Best Practices

Usage Notes

Next Steps

Learn More