Create buyer mapping

POST /api/v2/storefront/esa/{esaId}/buyer-advertiser-mappings Creates a per-buyer routing override on a GAM-backed embedded sales agent. The buyer is keyed on operatorDomain and can be narrowed by brandHouse, brandId, or principalId. A matching mapping takes precedence over the storefront default advertiser.

Request

curl -X POST https://api.interchange.io/api/v2/storefront/esa/123/buyer-advertiser-mappings \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operatorDomain": "buyer.example",
    "gamAdvertiserId": "4567890123"
  }'

{
  "operatorDomain": "buyer.example",
  "gamAdvertiserId": "4567890123",
  "brandHouse": "Acme Holdings",
  "brandId": "acme-beverages"
}

Parameters

Field	Type	Required	Notes
`esaId`	integer	Yes	Path. Embedded sales-agent connection id
`operatorDomain`	string	Yes	Buyer operator domain this mapping matches
`gamAdvertiserId`	string	Yes	GAM advertiser the matched buyer routes to
`brandHouse`	string \| null	No	Narrow the match to a brand house
`brandId`	string \| null	No	Narrow the match to a brand id
`principalId`	string \| null	No	Narrow the match to a buyer principal id

Response

{
  "id": "map-abc",
  "operatorDomain": "buyer.example",
  "brandHouse": null,
  "brandId": null,
  "principalId": null,
  "gamAdvertiserId": "4567890123",
  "createdAt": "2026-06-07T15:00:00.000Z",
  "updatedAt": "2026-06-07T15:00:00.000Z"
}

Returns 201. id is the mappingId you pass to update and delete. Unset narrowing fields come back as null.

Errors

400 VALIDATION_ERROR — missing operatorDomain or gamAdvertiserId, esaId is not a positive integer, or the ESA is not Google Ad Manager-backed.

See Errors for the full error contract.

Buyer routing tasks

All buyer-routing operations

List buyer mappings

See existing overrides

Update buyer mapping

Edit an existing mapping

Set default advertiser

The fallback for unmatched buyers

Buyer routing tasks Delete buyer mapping

⌘I

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Request

Parameters

Response

Errors

Buyer routing tasks

List buyer mappings

Update buyer mapping

Set default advertiser

​Request

​Parameters

​Response

​Errors

​Related

Buyer routing tasks

List buyer mappings

Update buyer mapping

Set default advertiser

Request

Parameters

Response

Errors

Related