Skip to main content

Documentation Index

Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt

Use this file to discover all available pages before exploring further.

既存のメディアバイを 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`);

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

ParameterTypeRequiredDescription
media_buy_idstringYes*更新対象のパブリッシャー側メディアバイ ID
buyer_refstringYes*更新対象のバイヤー参照 ID
start_timestringNo更新後の開始日時
end_timestringNo更新後の終了日時
pausedbooleanNoメディアバイ全体を一時停止/再開（true=停止、false=稼働）
packagesPackageUpdate[]Noパッケージ単位の更新（下記参照）
reporting_webhookobjectNoレポート用 Webhook 設定の更新（下記参照）
push_notification_configobjectNo非同期処理通知用 Webhook
*Either media_buy_id OR buyer_ref is required (not both)

​
Reporting Webhook オブジェクト

このメディアバイの自動レポート配信を設定します。
ParameterTypeRequiredDescription
urlstringYesWebhook エンドポイント URL
authenticationobjectYesschemes と credentials を持つ認証設定
reporting_frequencystringYeshourly / daily / monthly
requested_metricsstring[]No取得したい指標（未指定ならすべて）
tokenstringNo検証用のクライアントトークン（16 文字以上）
Note: reporting_webhook はキャンペーンの継続レポート設定、push_notification_config は「この更新が完了したら知らせて」といった非同期通知用です。

​
Package Update オブジェクト

ParameterTypeDescription
package_idstring更新対象のパブリッシャー側パッケージ ID
buyer_refstring更新対象のバイヤー参照 ID
pausedbooleanパッケージ単位で一時停止/再開（true=停止、false=稼働）
budgetnumber予算の更新値
impressionsnumberこのパッケージのインプレッション目標の更新値
pacingstringペーシング戦略の更新
bid_pricenumber入札額の更新（オークション商品のみ）
targeting_overlayTargetingOverlayターゲティング制約の更新
creative_assignmentsCreativeAssignment[]割り当てクリエイティブを置き換え（重み/プレースメント指定可）
creativesCreativeAsset[]新規クリエイティブをインラインでアップロード・割り当て（ライブラリ未登録であること）
*各パッケージ更新では package_id または buyer_ref のどちらかが必須

​
レスポンス

​
成功レスポンス

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

​
エラーレスポンス

FieldDescription
errorsArray 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 CodeDescriptionResolution
MEDIA_BUY_NOT_FOUNDMedia buy doesn’t existVerify media_buy_id or buyer_ref
PACKAGE_NOT_FOUNDPackage doesn’t existVerify package_id or buyer_ref
UPDATE_NOT_ALLOWEDField cannot be changedSee “What Can Be Updated” above
BUDGET_INSUFFICIENTNew budget below minimumIncrease budget amount
POLICY_VIOLATIONUpdate violates content policyReview policy requirements
INVALID_STATEOperation not allowed in current stateCheck campaign status
CREATIVE_ID_EXISTSCreative ID already exists in libraryUse 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:
  1. Verify Changes: Use get_media_buy_delivery to confirm updates
  2. Upload New Creatives: Use sync_creatives if creative assignments changed
  3. Monitor Performance: Track impact of changes on campaign metrics
  4. Optimize Further: Use provide_performance_feedback for ongoing optimization

​
Learn More