Replace ad-server config

PUT /api/v2/storefront/inventory-sources/{sourceId}/ad-server Sets the ad-server configuration on an ad-server-backed source. The body fully replaces the config (PUT semantics). PATCH /api/v2/storefront/inventory-sources/{sourceId}/ad-server is accepted as an alias with the same body and response, for clients migrating from the legacy /esa/ad-server route.

Request

curl -X PUT https://api.interchange.io/api/v2/storefront/inventory-sources/retail-gam/ad-server \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "google_ad_manager",
    "networkCode": "12345678"
  }'

{
  "type": "freewheel",
  "clientId": "fw-client-id",
  "clientSecret": "<FREEWHEEL_CLIENT_SECRET>",
  "environment": "production",
  "defaultAdvertiserId": "adv_88421"
}

{
  "type": "springserve",
  "email": "ops@retail-network.example.com",
  "password": "<SPRINGSERVE_PASSWORD>",
  "environment": "production",
  "defaultDemandPartnerId": 50231
}

Parameters

Field	Type	Required	Notes
`sourceId`	string (path)	Yes	Storefront-scoped inventory source ID
`type`	enum	Yes	Discriminator: `google_ad_manager`, `freewheel`, or `springserve`

google_ad_manager

Field	Type	Required	Notes
`networkCode`	string	Yes	Numeric GAM network code (1–32 digits). Scope3 manages the service-account credentials

freewheel

Field	Type	Required	Notes
`clientId`	string	Conditional	FreeWheel Publisher API client ID. Required with `clientSecret`; omit when using `apiToken`
`clientSecret`	string	Conditional	FreeWheel Publisher API client secret. Required with `clientId`. Write-only — never returned or persisted by Scope3
`username`	string	Conditional	Legacy FreeWheel username for password-grant authentication. Prefer `clientId` + `clientSecret`
`password`	string	Conditional	Legacy FreeWheel password for password-grant authentication. Write-only — never returned or persisted by Scope3
`apiToken`	string	Conditional	Pre-minted token; used only when no client ID/client secret is supplied. Testing only
`environment`	enum	No	`production` (default) or `staging`
`defaultAdvertiserId`	string	No	Default FreeWheel advertiser id (max 64)

springserve

Field	Type	Required	Notes
`email`	string	Conditional	Required for password grant; omit when using `apiToken`
`password`	string	Conditional	Required for password grant. Write-only — never returned or persisted by Scope3
`apiToken`	string	Conditional	Pre-minted token; used only when no email/password. Testing only
`environment`	enum	No	`production` (only supported value)
`defaultDemandPartnerId`	integer	No	Default SpringServe demand partner id

FreeWheel and SpringServe credentials are forwarded to the managed ad-server source at provision time and never persisted by Scope3 — only non-secret display fields (client ID/login, environment, default advertiser/demand-partner id) are stored on the connection row. For FreeWheel production setup, prefer client ID/client secret (the upstream source mints and auto-refreshes short-lived tokens); reserve pre-minted apiToken for testing.

Response

200 OK with the updated EsaConnection (see Get ad-server connection for the full shape):

{
  "id": "550199",
  "customerId": 4210,
  "tenantId": "tnt_retail_gam",
  "adServer": { "type": "google_ad_manager", "networkCode": "12345678" },
  "serviceAccountEmail": "retail-gam-4210@scope3-esa.iam.gserviceaccount.com",
  "lastError": null,
  "lastErrorCode": null,
  "updatedAt": "2026-05-02T09:14:00Z"
}

For Google Ad Manager, serviceAccountEmail is the address the publisher must grant access to in their GAM admin console before provisioning succeeds.

Errors

400 VALIDATION_ERROR — unknown type, missing credentials for the chosen adapter, or malformed networkCode.
401 UNAUTHORIZED — missing or invalid API key.
404 NOT_FOUND — no ad-server-backed source with this sourceId.

See Errors for the full error contract.

Inventory source tasks

All operations

Rotate credentials

In-place credential rotation

Test connection

Probe upstream reachability

Get ad-server connection

Connection state

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Request

Parameters

Response

Errors

Inventory source tasks

Rotate credentials

Test connection

Get ad-server connection

​Request

​Parameters

​Response

​Errors

​Related

Inventory source tasks

Rotate credentials

Test connection

Get ad-server connection

Request

Parameters

Response

Errors

Related