> ## 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.
# Inventory sources
> Bind AdCP-compatible agents and ad servers to your storefront so buyers can discover and transact against your inventory
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 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.
* **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 feed-backed modular 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
Every source on the storefront
Register an external AGENT source
Read one source by ID
Check source health and recent AdCP activity
Change fields, rotate auth, transition status
Remove a source and disable its agent
### Ad-server connection
Connection state for a managed source
Operational snapshot of the managed source
Historical sync runs for drill-down
Set GAM, FreeWheel, or SpringServe config
In-place credential rotation
### Lifecycle
Mint a one-time URL into the managed source
Probe upstream reachability
Force-refresh the status cache
Soft-delete the managed source
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](/v2/storefront/inventory-sources/modular-lifecycle)
for the full setup checklist, feed format, sequence, and examples.
End-to-end avails, reservation, execution handoff, release, and HITL workflow
Preview and author property/tag to key-value, ad-unit, or placement mappings
Runtime projection for a modular source
Write non-secret config for one module
## Related
Every operation in one place
End-to-end seller setup
How to inspect source health and recent ADCP calls
How buyers see your storefront
Shared error contract