Skip to main content
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"
  }'

​
Parameters

FieldTypeRequiredNotes
esaIdintegerYesPath. Embedded sales-agent connection id
operatorDomainstringYesBuyer operator domain this mapping matches
gamAdvertiserIdstringYesGAM advertiser the matched buyer routes to
brandHousestring | nullNoNarrow the match to a brand house
brandIdstring | nullNoNarrow the match to a brand id
principalIdstring | nullNoNarrow 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