Skip to main content
POST /api/v2/buyer/media-buys/batch MCP tool and api_call operation: create_media_buys This operation continues from the ext.interchange.execution_id returned by get_products. It can select inventory from several storefronts in one request. Interchange creates or updates one DRAFT campaign cart, then prepares one or more media buys grouped for bilateral seller execution.

​
Request

Proposal selections distribute totalBudget using the seller’s allocations. Omit totalBudget only when the proposal carries a recommended total. Product selections are for proposal-less products and may include pricingOptionId, budget, bidPrice, and targetingOverlay. When creating the campaign inline, do not set productIds; selections is the only cart mutation in this request. If discoveryId is present, it must equal productQueryId. The campaign and product query must belong to the same advertiser. New selections can only be staged into a DRAFT campaign; an ACTIVE campaign is accepted only for an unchanged execution retry. Proposal selection also requires the durable accepted-proposal set written by the current get_products flow. If an older execution predates that set, run get_products again; Interchange will not infer acceptance from the raw seller response.

​
Choose stage or execute

Use mode: "execute" as a one-call shortcut when the selected products can be submitted without reviewing the generated media buys. Interchange prepares the batch first, records that exact request as prepared, and then contacts sellers. Use mode: "stage" when the media buys need review or customization:
  1. Call create_media_buys with mode: "stage".
  2. Inspect the returned DRAFT media buys and update per-buy creatives, flight dates, pacing, or optimization goals as needed.
  3. Call execute_campaign for the returned campaign. Alternatively, repeat create_media_buys with the same product query, campaign, selections, and replace value, changing only mode to "execute".
The final execute submits those same DRAFT media buys. It does not reconcile the product query again or discard the intervening changes. Repeating an unchanged stage request is also a no-op. If preparation failed, the request is not marked prepared and an unchanged retry attempts preparation again.

​
Response

External seller mutations cannot be atomic. success: false includes an errors entry for each failed media buy; successful storefront buys remain successful. Retry the unchanged request to dispatch only work that is still DRAFT. The operation records a fingerprint on the campaign cart, so a completed product query cannot be replayed with a different selection. mediaBuyRefs returns lightweight IDs and statuses for up to 100 current buys; when mediaBuyRefsTruncated is true, use get_campaign to drill into the cart.

​
Errors

  • 400 VALIDATION_ERROR — unqualified IDs, an advertiser/campaign mismatch, a non-DRAFT cart, invalid campaign terms, a completed query replayed with different selections, or selections that cannot be priced/funded.
  • 403 ACCESS_DENIED — the caller cannot access the advertiser or campaign.
  • 404 NOT_FOUND — the product query, proposal, product, or campaign does not exist in the authenticated customer.
  • 409 CONFLICT — campaign budget, settlement, or seller state conflicts with the requested batch.

Get products across storefronts

Retrieve and refine the qualified proposals/products used by this operation