Skip to main content
PATCH /api/v2/storefront/esa/{esaId}/buyer-advertiser-mappings/{mappingId} Updates an existing per-buyer routing override on a GAM-backed embedded sales agent. Send only the fields you want to change — repoint the mapping to a different advertiser, or adjust its brand or principal narrowing. The buyer key (operatorDomain) is fixed; create a new mapping to route a different buyer.

​
Request

curl -X PATCH https://api.interchange.io/api/v2/storefront/esa/123/buyer-advertiser-mappings/map-abc \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gamAdvertiserId": "9988776655" }'

​
Parameters

FieldTypeRequiredNotes
esaIdintegerYesPath. Embedded sales-agent connection id
mappingIdstringYesPath. Mapping id from list or create
gamAdvertiserIdstring | nullNoRepoint the mapping to a different GAM advertiser
brandHousestring | nullNoUpdate the brand-house narrowing; null clears it
brandIdstring | nullNoUpdate the brand-id narrowing; null clears it
principalIdstring | nullNoUpdate the principal narrowing; null clears it

​
Response

{
  "id": "map-abc",
  "operatorDomain": "buyer.example",
  "brandHouse": null,
  "brandId": null,
  "principalId": null,
  "gamAdvertiserId": "9988776655",
  "createdAt": "2026-05-20T14:00:00.000Z",
  "updatedAt": "2026-06-07T15:30:00.000Z"
}
Returns the full mapping with the changes applied. updatedAt advances; createdAt and operatorDomain are unchanged.

​
Errors

  • 400 VALIDATION_ERROR — esaId is not a positive integer, mappingId is empty, 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

Find the mapping id

Create buyer mapping

Route a new buyer

Delete buyer mapping

Remove this mapping