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:
Authenticate every request with Authorization: Bearer $SCOPE3_API_KEY. The storefront is resolved from your API key’s account 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-account actions (for example, a seller approving an inbound link).
  • Lifecycle. A source moves through PENDING → ACTIVE → DISABLED. An ad-server-backed source is enabled unless deactivatedAt is set (null means enabled); whether it is live and sellable is derived at read time from the managed-source status endpoint (operational.isLive), not from a stored lifecycle field. Recent failures surface as lastErrorCode/lastError. The operator flow is the same: create the connection, save ad-server config, test it, launch into the admin UI, then deactivate or reactivate as needed.
  • Passthrough vs merchandising. An external sales-agent source can answer buyer briefs live in passthrough mode, or it can provide cached components that the Merchandising Agent composes into products. Component-cache health and live-source health are separate diagnostics.
  • Component cache. When a source supports cacheable raw products, Interchange stores those components for merchandising and wholesale-mode reads. Cache success means the source returns stable component ids, pricing, formats, property/selectors, delivery type, and execution metadata. A cache miss does not by itself mean live passthrough is broken.
  • 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 setup checklist, feed format, sequence, and examples.

Modular lifecycle guide

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

Author property and tag mappings

Preview and author property/tag to key-value, ad-unit, or placement mappings

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