Skip to main content
An inventory source is a named slot inside your storefront that your Merchandising Agent draws from when it answers buyer briefs. Each source wraps something the agent can call: an external AdCP-compatible sales agent, an operator-owned ad server with Interchange-managed sales-agent plumbing behind it (an ad-server-backed source), a linked storefront, or a modular source assembled from individual modules. Buyers never target a source directly — they call your storefront, and discovery or media-buy calls route through the active source behind it. All examples use the storefront base URL: 
https://api.interchange.io/api/v2/storefront
Authenticate every request with Authorization: Bearer $SCOPE3_API_KEY. The storefront is resolved from your API key’s customer context — there is no customerId path parameter.

​
Key concepts

  • Execution type. Every source has an executionType: AGENT (external AdCP sales/signal/creative/outcome agent), MANAGED_SALES_AGENT (ad-server-backed source — GAM, FreeWheel, or SpringServe), LINKED_STOREFRONT, or MODULAR_SOURCE. Only AGENT sources are created and updated through the generic inventory-source endpoints; the other kinds use dedicated provisioning and linking flows.
  • Two identifiers. sourceId is unique within your storefront and is what you use for actions on your own rows. id is a globally unique surrogate used for cross-customer actions (for example, a seller approving an inbound link).
  • Lifecycle. A source moves through PENDING → ACTIVE → DISABLED. Ad-server-backed sources carry an additional provisioningStatus (pending, provisioning, active, failed, deactivated) that tracks the upstream managed source: create the connection, save ad-server config, test it, launch into the admin UI, then deactivate or reactivate as needed.
  • Credentials are never echoed. Agent API keys and JWT private keys are encrypted at rest and referenced by an opaque ref. Responses surface authConfigured: true instead of the raw secret.
  • Modular readiness. A MODULAR_SOURCE is composed of typed modules (inventory feed, booking ledger, trafficking, status sync, reporting import). Its readiness projection reports per-module contracts, lifecycle stages, missing setup fields, and open work-item counts.
Sources can’t be deleted while their backing agent has non-terminal media buys (ACTIVE, PAUSED, PENDING_APPROVAL, or INPUT_REQUIRED). Cancel or terminate those first.

​
Task reference

​
Manage

List inventory sources

Every source on the storefront

Create inventory source

Register an external AGENT source

Get inventory source

Read one source by ID

Diagnose third-party sales agents

Check source health and recent AdCP activity

Update inventory source

Change fields, rotate auth, transition status

Delete inventory source

Remove a source and disable its agent

​
Ad-server connection

Get ad-server connection

Connection state for a managed source

Get status

Operational snapshot of the managed source

List sync history

Historical sync runs for drill-down

Replace ad-server config

Set GAM, FreeWheel, or SpringServe config

Rotate credentials

In-place credential rotation

​
Lifecycle

Launch admin UI

Mint a one-time URL into the managed source

Test connection

Probe upstream reachability

Refresh

Force-refresh the status cache

Deactivate

Soft-delete the managed source

Reactivate

Re-enable a deactivated source

​
Modular

Modular sources use a staged operator lifecycle: ingest avails, inspect product projections, reserve capacity, prepare supported execution handoffs, release capacity when needed, and work any source-side human queue items. See the modular lifecycle guide for the full sequence and examples.

Modular lifecycle guide

End-to-end avails, reservation, execution handoff, release, and HITL workflow

Get modular readiness

Runtime projection for a modular source

Update module config

Write non-secret config for one module

All inventory-source tasks

Every operation in one place

Storefront onboarding

End-to-end seller setup

Diagnose third-party sales agents

How to inspect source health and recent ADCP calls

Storefront object guide

How buyers see your storefront

Errors

Shared error contract