> ## 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.

# List buyer mappings

> List buyer-to-GAM advertiser routing overrides for an ESA

`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

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.interchange.io/api/v2/storefront/esa/123/buyer-advertiser-mappings?operatorDomain=buyer.example" \
    -H "Authorization: Bearer $SCOPE3_API_KEY"
  ```
</CodeGroup>

## Parameters

| Field             | Type    | Required | Notes                                                      |
| ----------------- | ------- | -------- | ---------------------------------------------------------- |
| `esaId`           | integer | Yes      | Path. Embedded sales-agent connection id                   |
| `operatorDomain`  | string  | No       | Query. Return only mappings for this buyer operator domain |
| `operator_domain` | string  | No       | Query. Alias for `operatorDomain`                          |

## Response

```json theme={null}
{
  "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](/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="Create buyer mapping" href="/v2/storefront/buyer-routing/tasks/create-buyer-mapping" icon="link">
    Route a buyer to an advertiser
  </Card>

  <Card title="Update buyer mapping" href="/v2/storefront/buyer-routing/tasks/update-buyer-mapping" icon="pen">
    Edit an existing mapping
  </Card>

  <Card title="List recent buyers" href="/v2/storefront/buyer-routing/tasks/list-recent-buyers" icon="clock-rotate-left">
    See which buyers need a mapping
  </Card>
</CardGroup>