Skip to main content
GET /api/v2/storefront/esa/{esaId}/buyer-advertiser-mappings Lists the per-buyer routing overrides on a GAM-backed embedded sales agent. Each mapping points one buyer — keyed on operatorDomain and optionally narrowed by brand or principal — at a specific GAM advertiser, taking precedence over the default. Filter to a single buyer with operatorDomain.

​
Request

curl "https://api.interchange.io/api/v2/storefront/esa/123/buyer-advertiser-mappings?operatorDomain=buyer.example" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

​
Parameters

FieldTypeRequiredNotes
esaIdintegerYesPath. Embedded sales-agent connection id
operatorDomainstringNoQuery. Return only mappings for this buyer operator domain
operator_domainstringNoQuery. Alias for operatorDomain

​
Response

{
  "mappings": [
    {
      "id": "map-abc",
      "operatorDomain": "buyer.example",
      "brandHouse": "Acme Holdings",
      "brandId": "acme-beverages",
      "principalId": null,
      "gamAdvertiserId": "4567890123",
      "createdAt": "2026-05-20T14:00:00.000Z",
      "updatedAt": "2026-05-20T14:00:00.000Z"
    }
  ],
  "count": 1
}
Each id is the mappingId you pass to update and delete. brandHouse, brandId, and principalId narrow the match and may be null. gamAdvertiserId is the advertiser the matched buyer routes to.

​
Errors

  • 400 VALIDATION_ERROR — 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

Create buyer mapping

Route a buyer to an advertiser

Update buyer mapping

Edit an existing mapping

List recent buyers

See which buyers need a mapping