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

# Buyer routing

> Map incoming buyers to Google Ad Manager advertisers for ad-server-backed sources

Buyer routing decides which Google Ad Manager advertiser a buyer's spend books against when your storefront draws from a Google Ad Manager-backed embedded sales agent (ESA). Every incoming buyer resolves to exactly one GAM advertiser: a per-buyer **mapping** if one matches, otherwise the storefront's **default advertiser** catch-all.

* **Default advertiser** — the catch-all every unmatched buyer routes to. Set it once with `PUT /esa/{esaId}/gam/default-advertiser`. Until it is set, the `Default GAM advertiser` setup blocker stays open.
* **Per-buyer mappings** — override the default for a specific buyer, keyed on `operatorDomain` (optionally narrowed by `brandHouse`, `brandId`, or `principalId`). A matching mapping wins over the default.
* **Recent buyers** — the buyers the ESA has actually seen, with whether each resolved through the default or a specific mapping, so you can spot buyers that need their own advertiser.

GAM advertiser records are cached from the upstream network. List them to find the `id` you pass as the default or as a mapping target, or call ensure to create-or-find one by name.

An inventory sync can succeed even when the GAM credential cannot see any
advertisers: inventory and companies are separate GAM permissions. If the
advertiser cache reports zero records, confirm that the Interchange service
account is an active GAM API user and that its role and teams grant access to
the intended advertisers. Then refresh the source. Do not interpret a healthy
inventory count as proof that advertiser access is configured.

For a managed GAM connection, use the dedicated **Interchange - Default**
advertiser as the fallback. You do not need a GAM advertiser per end advertiser
unless you want a buyer-specific routing override. Safe no-spend tests use a
separate **Interchange - Sandbox** advertiser; Interchange never falls back to
the production default advertiser for a sandbox test.

All examples use the storefront base URL:

```
https://api.interchange.io/api/v2/storefront
```

Authenticate every request with `Authorization: Bearer $SCOPE3_API_KEY`. The `{esaId}` path parameter is the embedded sales-agent connection id.

## Task reference

<CardGroup cols={2}>
  <Card title="List GAM advertisers" href="/v2/storefront/buyer-routing/tasks/list-gam-advertisers" icon="list">
    `GET /esa/{esaId}/gam/advertisers` — cached advertiser records
  </Card>

  <Card title="Ensure GAM advertiser" href="/v2/storefront/buyer-routing/tasks/ensure-gam-advertiser" icon="plus">
    `POST /esa/{esaId}/gam/advertisers/ensure` — create or find by name
  </Card>

  <Card title="Set default advertiser" href="/v2/storefront/buyer-routing/tasks/set-default-advertiser" icon="star">
    `PUT /esa/{esaId}/gam/default-advertiser` — the catch-all advertiser
  </Card>

  <Card title="List buyer mappings" href="/v2/storefront/buyer-routing/tasks/list-buyer-mappings" icon="table-list">
    `GET /esa/{esaId}/buyer-advertiser-mappings` — per-buyer overrides
  </Card>

  <Card title="Create buyer mapping" href="/v2/storefront/buyer-routing/tasks/create-buyer-mapping" icon="link">
    `POST /esa/{esaId}/buyer-advertiser-mappings` — route one buyer
  </Card>

  <Card title="Update buyer mapping" href="/v2/storefront/buyer-routing/tasks/update-buyer-mapping" icon="pen">
    `PATCH /esa/{esaId}/buyer-advertiser-mappings/{mappingId}` — edit a mapping
  </Card>

  <Card title="Delete buyer mapping" href="/v2/storefront/buyer-routing/tasks/delete-buyer-mapping" icon="trash">
    `DELETE /esa/{esaId}/buyer-advertiser-mappings/{mappingId}` — remove a
    mapping
  </Card>

  <Card title="List recent buyers" href="/v2/storefront/buyer-routing/tasks/list-recent-buyers" icon="clock-rotate-left">
    `GET /esa/{esaId}/recent-buyers` — buyers seen and how they resolved
  </Card>
</CardGroup>