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

# Create buyer mapping

> Route one buyer to a specific GAM advertiser on an ESA

`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

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

  ```json Narrowed by brand theme={null}
  {
    "operatorDomain": "buyer.example",
    "gamAdvertiserId": "4567890123",
    "brandHouse": "Acme Holdings",
    "brandId": "acme-beverages"
  }
  ```
</CodeGroup>

## Parameters

| Field             | Type           | Required | Notes                                      |
| ----------------- | -------------- | -------- | ------------------------------------------ |
| `esaId`           | integer        | Yes      | Path. Embedded sales-agent connection id   |
| `operatorDomain`  | string         | Yes      | Buyer operator domain this mapping matches |
| `gamAdvertiserId` | string         | Yes      | GAM advertiser the matched buyer routes to |
| `brandHouse`      | string \| null | No       | Narrow the match to a brand house          |
| `brandId`         | string \| null | No       | Narrow the match to a brand id             |
| `principalId`     | string \| null | No       | Narrow the match to a buyer principal id   |

## Response

```json theme={null}
{
  "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](/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">
    See existing overrides
  </Card>

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

  <Card title="Set default advertiser" href="/v2/storefront/buyer-routing/tasks/set-default-advertiser" icon="star">
    The fallback for unmatched buyers
  </Card>
</CardGroup>