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

# Replace ad-server config

> Set the ad-server configuration on an ad-server-backed inventory source

`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

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

  ```json FreeWheel theme={null}
  {
    "type": "freewheel",
    "clientId": "fw-client-id",
    "clientSecret": "<FREEWHEEL_CLIENT_SECRET>",
    "environment": "production",
    "defaultAdvertiserId": "adv_88421"
  }
  ```

  ```json SpringServe theme={null}
  {
    "type": "springserve",
    "email": "ops@retail-network.example.com",
    "password": "<SPRINGSERVE_PASSWORD>",
    "environment": "production",
    "defaultDemandPartnerId": 50231
  }
  ```
</CodeGroup>

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

<Warning>
  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.
</Warning>

## Response

`200 OK` with the updated `EsaConnection` (see [Get ad-server connection](/v2/storefront/inventory-sources/tasks/get-ad-server-connection) for the full shape):

```json theme={null}
{
  "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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Inventory source tasks" href="/v2/storefront/inventory-sources/tasks" icon="list-check">
    All operations
  </Card>

  <Card title="Rotate credentials" href="/v2/storefront/inventory-sources/tasks/rotate-credentials" icon="key">
    In-place credential rotation
  </Card>

  <Card title="Test connection" href="/v2/storefront/inventory-sources/tasks/test-connection" icon="plug-circle-check">
    Probe upstream reachability
  </Card>

  <Card title="Get ad-server connection" href="/v2/storefront/inventory-sources/tasks/get-ad-server-connection" icon="server">
    Connection state
  </Card>
</CardGroup>