> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update buyer mapping

> Edit an existing buyer-to-GAM advertiser routing override

`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

<CodeGroup>
  ```bash curl theme={null}
  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" }'
  ```
</CodeGroup>

## Parameters

| Field             | Type           | Required | Notes                                                                                          |
| ----------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `esaId`           | integer        | Yes      | Path. Embedded sales-agent connection id                                                       |
| `mappingId`       | string         | Yes      | Path. Mapping id from [list](/v2/storefront/buyer-routing/tasks/list-buyer-mappings) or create |
| `gamAdvertiserId` | string \| null | No       | Repoint the mapping to a different GAM advertiser                                              |
| `brandHouse`      | string \| null | No       | Update the brand-house narrowing; `null` clears it                                             |
| `brandId`         | string \| null | No       | Update the brand-id narrowing; `null` clears it                                                |
| `principalId`     | string \| null | No       | Update the principal narrowing; `null` clears it                                               |

## Response

```json theme={null}
{
  "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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Buyer routing tasks" href="/v2/storefront/buyer-routing/tasks" icon="list-check">
    All buyer-routing operations
  </Card>

  <Card title="List buyer mappings" href="/v2/storefront/buyer-routing/tasks/list-buyer-mappings" icon="table-list">
    Find the mapping id
  </Card>

  <Card title="Create buyer mapping" href="/v2/storefront/buyer-routing/tasks/create-buyer-mapping" icon="link">
    Route a new buyer
  </Card>

  <Card title="Delete buyer mapping" href="/v2/storefront/buyer-routing/tasks/delete-buyer-mapping" icon="trash">
    Remove this mapping
  </Card>
</CardGroup>