Skip to main content
Buyer routing decides which ad-server advertiser a buyer’s spend books against when your storefront draws from an embedded sales agent (ESA). Every incoming buyer resolves to exactly one 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}/default-advertiser, whichever ad server backs the source. 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.

​
Finding an advertiser id

The provider-neutral endpoint returns bounded advertiser pages for supported ad servers. Google Ad Manager also keeps its dedicated filtered search endpoint: Pass limit (up to 500) and cursor to page through the provider-neutral endpoint. Follow nextCursor until it is null. authoritative: true means the source completed its bounded read; truncated: true or a non-empty errors list means the response must not be used to infer that an omitted advertiser was removed.
Setting the default advertiser works on Google Ad Manager and AdsWizz sources. Per-buyer mappings are still Google Ad Manager only — on AdsWizz, every buyer routes to the default advertiser.FreeWheel and SpringServe still do not support a tenant default through this buyer-routing surface, for different reasons. SpringServe has no advertiser in its model at all. FreeWheel advertiser IDs are available for explicit Buyer Account Mapping source bindings, but the tenant-default write is not supported.
An inventory sync can succeed even when the ad-server credential cannot see any advertisers: inventory and companies are separate permissions. If the advertiser list reports zero records, confirm that the Interchange service account has advertiser read access. Then retry. 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:
Authenticate every request with Authorization: Bearer $SCOPE3_API_KEY. The {esaId} path parameter is the embedded sales-agent connection id.

​
Task reference

List adapter advertisers

GET /esa/{esaId}/advertisers — bounded provider-neutral advertiser pages

List GAM advertisers

GET /esa/{esaId}/gam/advertisers — cached GAM advertiser records

Ensure GAM advertiser

POST /esa/{esaId}/gam/advertisers/ensure — create or find by name

Set default advertiser

PUT /esa/{esaId}/default-advertiser — the catch-all advertiser

List buyer mappings

GET /esa/{esaId}/buyer-advertiser-mappings — per-buyer overrides

Create buyer mapping

POST /esa/{esaId}/buyer-advertiser-mappings — route one buyer

Update buyer mapping

PATCH /esa/{esaId}/buyer-advertiser-mappings/{mappingId} — edit a mapping

Delete buyer mapping

DELETE /esa/{esaId}/buyer-advertiser-mappings/{mappingId} — remove a mapping

List recent buyers

GET /esa/{esaId}/recent-buyers — buyers seen and how they resolved