Skip to main content
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"
  }'

​
Parameters

FieldTypeRequiredNotes
sourceIdstring (path)YesStorefront-scoped inventory source ID
typeenumYesDiscriminator: google_ad_manager, freewheel, or springserve
google_ad_manager
FieldTypeRequiredNotes
networkCodestringYesNumeric GAM network code (1–32 digits). Scope3 manages the service-account credentials
freewheel
FieldTypeRequiredNotes
usernamestringConditionalRequired for password grant; omit when using apiToken
passwordstringConditionalRequired for password grant. Write-only — never returned or persisted by Scope3
apiTokenstringConditionalPre-minted token; used only when no username/password. Testing only
environmentenumNoproduction (default) or staging
defaultAdvertiserIdstringNoDefault FreeWheel advertiser id (max 64)
springserve
FieldTypeRequiredNotes
emailstringConditionalRequired for password grant; omit when using apiToken
passwordstringConditionalRequired for password grant. Write-only — never returned or persisted by Scope3
apiTokenstringConditionalPre-minted token; used only when no email/password. Testing only
environmentenumNoproduction (only supported value)
defaultDemandPartnerIdintegerNoDefault 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 (login, environment, default advertiser/demand-partner id) are stored on the connection row. For production, prefer username/password (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,
  "provisioningStatus": "active",
  "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