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 wholesale inputs that the Merchandising Agent composes into products. A complete third-party sales agent starts in passthrough: Interchange forwards the buyer’s get_products brief to it, and it returns its own finished products, pricing, and media-buy behavior. This ordinary path does not use ingredients. Interchange product composition is a separate paid add-on for sellers who want Interchange to build and merchandise products. When that add-on is on, an external source contributes composition inputs only when it advertises and implements the AdCP 3.1+ wholesale product contract. Component-cache health and live-source health are separate diagnostics.
  • Managed sources require composition. An active ad-server-backed source always turns composition on because raw ad-server inventory must be converted into sellable products. If a storefront later connects a complete third-party sales agent and intends to use it alone, deactivate the old managed source; otherwise its presence continues to lock the storefront in composition mode.
  • Component cache. When a composition-enabled source supports AdCP 3.1+ wholesale products, Interchange stores those inputs 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.
  • Connection definitions are versioned. The external sales-agent Task pins the endpoint, protocol, and authentication definition used during setup. Built-in and Partner-backed integrations use the same typed definition model, while older integrations keep their existing setup path until migrated.
  • 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.

​
Working with an ad-server source in Murph

Ad-server setup is separated by job so first-time connection does not compete with operational detail:
  1. Connect ad server is a one-completion task. Choose the provider, enter the account or credential details it requires, create the source, and the task closes.
  2. Ad server source is the return page for an existing source: current posture, default-advertiser work, configuration, and deactivation.
  3. Sync & diagnostics is the evidence page for source health, sync streams and run history, and buyer-discovery cache freshness. It appears when you ask for diagnostics or follow a source problem; it is not a permanent green setup step.
If part of the diagnostics payload is temporarily unavailable, Murph names the missing evidence and keeps the rest visible instead of treating a failed read as an empty or healthy result.

​
Add another source

Open Seller Setup and use its Inventory sources section whenever you want to connect a second or later source. The same Page offers direct actions for an ad server, a modular inventory source, or an external AdCP sales agent. Each action opens the source’s structured setup flow; it does not turn the button click into a new chat prompt. Adding a source keeps the storefront settings you already completed: currency, approval routing, business profile, publisher domains, acceptance policy, and selling rules. The new source gets its own connection, credentials, catalog, health, and setup work. Seller Setup lists those facts per source, so a healthy first source cannot hide a second source that is still waiting for credentials, sync, products, or repair.
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