> ## 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.
# Modular inventory source lifecycle
> Upload avails, inspect product projections, reserve capacity, prepare supported execution handoffs, and manage source-side human work
A **modular inventory source** is an operator-managed source composed from smaller modules: an inventory feed, an optional booking ledger, optional execution modules, and optional human work queues. The storefront still presents one buyer-facing sales-agent surface. The modules describe how that source gets inventory, prevents overbooking, books upstream supply, traffics campaigns, syncs creatives, and imports reporting.
Use a modular source when inventory and execution do not come from one fully compliant upstream sales agent. For example, a publisher may send a periodic avails spreadsheet, confirm bookings manually, traffic a campaign in an addressable TV system, and upload the final delivery report after the campaign ends.
Modular source operations are storefront-operator endpoints. Buyer agents do not call them directly. Buyers still transact through the storefront's AdCP media-buy workflow.
Modular inventory sources are currently feature flagged for pilot customers. If an operation returns `FEATURE_NOT_ENABLED`, ask your Scope3 contact to enable the `modular-inventory-sources` pilot for your storefront account.
All examples use the storefront base URL:
```bash theme={null}
export BASE=https://api.interchange.io/api/v2/storefront
export SCOPE3_API_KEY=scope3_
```
## When to use a modular source
Set up your storefront first, then decide which source type each inventory
system should become:
| Source type | Use it when |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| External sales agent | The vendor already runs a compliant AdCP sales agent that buyers can use through your storefront. |
| Ad-server-backed source | Scope3 has a managed integration for your ad server, such as GAM, FreeWheel, or SpringServe. |
| Linked storefront | Another Interchange storefront should supply products or execution. |
| Modular source | Inventory, booking, creative, trafficking, and reporting live in different systems or human workflows. |
A modular source is the right pilot shape when the seller can provide a feed of
wholesale inventory but cannot yet expose the whole lifecycle through one
upstream API.
A manual or back-office source is modular because no single system can answer
the complete AdCP workflow. A spreadsheet may describe what can be sold, an OMS
may record the booking, an ad server may execute it, and a person may move the
creative or final report between them. Modeling those responsibilities as
modules makes every supported and human-owned step explicit without claiming
automation that is not connected.
## Modules
Each module owns one part of the lifecycle. A source can start with manual
modules and later replace a step with an automated integration.
| Module | Purpose | Typical input |
| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Inventory feed | Ingest wholesale avails and project buyer-facing products. | CSV, TSV, XLSX, XLS, or JSON upload. |
| Booking ledger | Hold and book capacity so the storefront does not overbook what it controls. | Reserved and booked impressions keyed by `availId` and media-buy id. |
| Booking execution | Confirm the upstream booking in an OMS, ad server, or human queue. | OMS API details, booking owner, or required human task fields. |
| Creative sync | Map accepted buyer creative to the upstream system before go-live. | Creative specs, approval owner, and upstream creative reference. |
| Trafficking | Push or manually enter campaign details in the execution system. | Campaign name, advertiser, dates, products, budget, creative refs. |
| Reporting import | Bring back final delivery after the campaign ends. | Delivery export with delivered impressions and upstream references. |
Every modular setup must account for these lifecycle responsibilities, even
when the current answer is a named human rather than an integration:
| Responsibility | Decide during setup |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Catalog and avails | Who supplies current sellable rows, prices, dates, capacity, and stable ids; how often they refresh. |
| Booking and execution | What reserves capacity, what confirms the upstream order, who traffics it, and which event means it is live. |
| Creative | Who validates specifications and approvals, and how buyer creative receives an upstream reference. |
| Reporting | Who exports delivery, which identifiers reconcile it to the booking, and when final data is available. |
| Readiness | Which required modules, credentials, runtime inputs, and test results must be complete before this source can sell. |
| Human in the loop (HITL) | Which steps create a work item, who owns it, what evidence completes it, and how quickly it must be handled. |
Manual ownership does not make a stage `READY`. Readiness is reported from the
configured modules and runtime inputs; a human-owned stage can remain
`HITL_PENDING`, `MISSING_SETUP`, or `UNSUPPORTED` until its requirements are
met.
The CitrusAd pilot is a **standard composition**, so sellers connect it as an
ad server rather than assembling modules. It uses a retailer-namespace catalog
module and a campaign-execution module behind one inventory source. The
storefront remains in `CHEF` routing mode; buyers see the storefront, not a
CitrusAd adapter or the private module graph. This standard ad-server flow is
available independently of the advanced modular-source pilot flag.
The first recipe supports sponsored-product campaigns. Their creative is
rendered from retailer catalog data, so creative sync completes without an
asset upload. CitrusAd also offers static banners and Banner X, but those are
not exposed by this recipe until separate banner campaign and creative APIs are
implemented and verified.
Connect the standard recipe through
`POST /inventory-sources/ad-servers/citrusad`, then save the storefront-scoped
credential through
`POST /inventory-sources/{sourceId}/ad-servers/citrusad/credentials/{credentialKind}`.
These ad-server endpoints do not expose the private module graph.
## Module credentials
Credentials belong to one module instance on one storefront inventory source.
They are not process environment variables and are not shared across
storefronts. Raw `auth` values are written to the configured secret manager;
the API response contains status, scopes, expiry, and other non-secret metadata
only. Credential mutations require a storefront admin role or the dedicated
`StorefrontCredentialsAdmin` permission.
Create a credential with `POST`, rotate it with `PUT`, and revoke it with
`DELETE` at:
```text theme={null}
/inventory-sources/{sourceId}/modular/modules/{moduleInstanceId}/credentials/{credentialKind}
```
`credentialKind` is `API_KEY`, `BEARER`, or `OAUTH`. For example:
```bash theme={null}
curl -X POST "$BASE/inventory-sources/retail-modular/modular/modules/citrus-campaign/credentials/API_KEY" \
-H "Authorization: Bearer $SCOPE3_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"auth": { "userKey": "" },
"scopes": ["campaigns:write"]
}'
```
Credential-shaped fields are rejected from module config and credential
metadata. Put all provider secrets under `auth`.
Storefront-level approval policies still apply outside the modular source. For
example, advertiser approval and creative review can happen before a modular
source asks a human to map the approved creative into an upstream ad server.
## Seller setup checklist
Ask the seller for whatever they already have, then classify each file into one
of these setup areas:
| Area | What good input looks like |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Business profile | Channels, markets, verticals, brand voice, sales owners, and seller positioning. |
| Properties and collections | Publisher domains, apps, channels, platforms, shows, networks, or collections, plus `adagents.json` ownership. |
| Products and signals | Durable packages, targeting dimensions, audience/context signals, and creative formats. |
| Avails feed | Row-level availability with stable ids, dates, capacity, price, and collection mapping. |
| Bookings/reservations | Upstream commitments already sold outside the storefront, if the avails feed is gross capacity. |
| Creative workflow | Specs, restrictions, approval owner, due dates, and upstream creative id requirements. |
| Trafficking workflow | OMS/ad-server owner or API, required ids, and what confirms a booking. |
| Reporting workflow | Sample final report export and the columns needed to reconcile delivery. |
| Owners and service levels | A named owner for booking, creative, trafficking, and reporting work, plus expected turnaround and escalation contacts. |
Prepare representative materials next: a real avails export, existing booking
or reservation export, creative specifications and approval rules, a sample
trafficking order, and a sample delivery report. Include the identifiers used
to join those artifacts and name the human owner for every manual handoff. A
media kit or rate card is useful context, but it does not replace row-level
avails or lifecycle evidence.
Media kits, co-viewing studies, market-size notes, and screenshots are useful
context. They are not avails feeds unless they contain row-level sellable
capacity for a specific collection and time window.
## The three setup surfaces in chat
Setting up and running a feed-backed source is three surfaces, each with one
job. Ask Murph for any of them by name, or move between them from the
workspace.
| Surface | What it is for | How it ends |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| **Add a feed-backed source** | Register a new source: its name, where its avails come from, and how often they arrive. | Closes when the source is created and opens its workspace. |
| **Feed-backed source workspace** | The place you return to for an existing source: how ready each lifecycle stage is, which modules are attached, and the work waiting on a person. | Stays open; refreshes as you work. |
| **Commit avails feed** | Turn an avails export into sellable capacity. | Closes when rows are committed and returns you to the workspace. |
Two things follow from that split:
* **Creating a source does not ask how you book, traffic, clear creative, or
report.** Those are derived per lifecycle stage from the modules attached to
the source, and shown in the workspace — see
[Check readiness](#1-check-readiness). Every feed-backed source starts with an
avails-feed module and Interchange's booking ledger.
* **Nothing is offered to buyers until avails rows are committed.** A source
with no committed rows is registered but has no sellable capacity.
## Avails feed requirements
The first successful upload should be boring: one row per sellable line, with
stable ids and clear capacity semantics.
Required columns:
| Column | Meaning |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | Stable seller-side id for the container. |
| `collectionName` | Seller-facing collection name. |
| `availId` | Stable seller-side id for this availability row. If missing, Interchange can derive one, but explicit ids are better. |
| `name` | Seller-facing row name. |
| `startTime` | ISO date or date-time for the availability window start. |
| `endTime` | ISO date or date-time for the availability window end. |
| `impressionsCapacity` | Net sellable impressions available to this storefront. |
Optional columns:
| Column | Meaning |
| -------------------------------------------------- | ---------------------------------------------------- |
| `cpm`, `rateCpm`, or `priceCpm` | CPM for this row. |
| `currency` | ISO currency code. |
| `channel` or `mediaChannel` | CTV, audio, OLV, display, home screen, podcast, etc. |
| `targeting` | JSON object with structured targeting facts. |
| `sourceMetadata`, `source_metadata`, or `metadata` | JSON object with source details. |
| Any other column | Preserved as source metadata when possible. |
If the seller only has gross capacity, include one of `avails`, `impressions`,
`monthlyAvails`, `monthlyVideoAvails`, or `monthlyHomeScreenAvails`, plus
`bookedImpressions`, `upstreamBookedImpressions`, `booked`, or
`reservedImpressions`. Preview will calculate net capacity as:
```text theme={null}
impressionsCapacity = max(0, gross capacity - upstream booked capacity)
```
Supported upload formats are CSV, TSV, XLSX, XLS, and JSON. Numeric fields can
use plain numbers or common suffixes such as `150m`, `25 million`, or `1.5B`.
```csv theme={null}
collectionId,collectionName,availId,name,startTime,endTime,impressionsCapacity,bookedImpressions,channel,market,cpm,currency
publisher-ctv,Publisher CTV,publisher-ctv-2026-07,CTV July,2026-07-01,2026-08-01,150000000,25000000,CTV,US,24.00,USD
publisher-home-screen,Publisher Home Screen,publisher-home-2026-07,Home Screen July,2026-07-01,2026-08-01,1.5B,100m,CTV,US,12.00,USD
```
## Murph walkthrough
Murph should not force a seller into a blank template. A good setup conversation
looks like this:
1. Ask the seller to upload what they have: deck, media kit, rate card,
publisher list, avails export, booking export, creative specs, reporting
export, or screenshots.
2. Classify the material. Keep market context as context; do not commit it as
avails.
3. Ask for missing row-level avails if the seller only supplied market scale.
4. Create the feed-backed modular source only after the operator confirms the
source name and lifecycle plan.
5. Preview the feed. Show normalized rows and whether capacity is net or
gross-minus-booked.
6. Commit only after explicit confirmation.
7. Run a small test reservation and validate the handoff requirements. Only run
finalization when the source has a real execution module or a configured demo
execution module.
8. Route unsupported integrations or missing systems into the normal Murph
escalation flow so the need is tracked centrally.
For example, a note that says "150 million monthly video avails and 1.5 billion
home-screen avails" is not enough to launch. Murph should ask for actual rows
with collection names, stable ids, dates, net capacity or booked counts, pricing,
and reporting/booking ownership.
## 1. Check readiness
Start with the runtime projection:
```bash theme={null}
curl "$BASE/inventory-sources/retail-modular/modular" \
-H "Authorization: Bearer $SCOPE3_API_KEY"
```
The response includes `lifecycleSummary`, one row per stage:
| Status | Meaning |
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `UNSUPPORTED` | No active module implements this stage. |
| `MISSING_SETUP` | A module supports the stage, but required module config is missing. |
| `RUNTIME_INPUTS_REQUIRED` | Setup is complete, but the stage needs runtime input such as an avails feed, creative, or report upload. |
| `HITL_PENDING` | A human work item is open for this stage. |
| `READY` | The stage has enough setup and runtime inputs for the current source state. |
| `BLOCKED` | A module has an error or source-health issue that needs operator attention. |
`activeAvailCount` tells you whether the source currently has usable avails. `openWorkItemCountsByKind` tells you what human queue is blocking a module or stage, for example `MAP_CREATIVE_REF` or `UPLOAD_FINAL_REPORT`.
## 2. Preview, then commit avails
An inventory-feed module accepts normalized avails. The feed can come from a publisher upload, a pasted CSV/JSON payload, or a file that Murph has parsed into rows. Murph previews parsed rows first; commit the feed only after an operator confirms the normalized rows and confirms `impressionsCapacity` is net sellable capacity.
A preview is row-tolerant: one invalid row does not hide valid rows. The response
returns normalized accepted rows in `avails`, invalid source rows in
`rejectedRows`, and non-blocking normalization facts in `warnings`, with matching
counts. Each diagnostic has a stable `code`, source `rowNumber`, safe `message`,
and `field` when the field is known. Commit by sending only the accepted `avails`
back with `confirmed: true`; rejected rows and warnings are never committed.
Current row diagnostic codes are `REQUIRED_FIELD_MISSING`, `INVALID_DATE_TIME`,
`INVALID_NUMBER`, and `GROSS_CAPACITY_NORMALIZED`. The last is a warning that
net sellable capacity was calculated by subtracting upstream booked impressions
from gross capacity.
```bash theme={null}
curl -X POST "$BASE/inventory-sources/retail-modular/modular/avails-feed" \
-H "Authorization: Bearer $SCOPE3_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"confirmed": true,
"avails": [
{
"availId": "sports-week-2026-07",
"collectionId": "connected-tv",
"collectionName": "Connected TV",
"name": "Sports week CTV impressions",
"startTime": "2026-07-01T00:00:00.000Z",
"endTime": "2026-07-31T23:59:59.000Z",
"impressionsCapacity": 1500000,
"cpm": 22,
"currency": "USD",
"targeting": {
"market": "South Africa",
"screen": "CTV"
},
"sourceMetadata": {
"publisher": "Example Network",
"upstreamBookedImpressions": 300000
}
}
]
}'
```
Ingestion upserts by `availId`. If an avail already has held or booked impressions, the feed update will not reduce capacity below those commitments.
## 3. Inspect product projections
List the product-like projections generated from active avails:
```bash theme={null}
curl "$BASE/inventory-sources/retail-modular/modular/products" \
-H "Authorization: Bearer $SCOPE3_API_KEY"
```
Each product maps back to one normalized avail. Generic feed-only sources return `cadent: null`. Cadent fields appear only when the source has an active Cadent execution module, so uploaded publisher avails are not implicitly treated as Cadent-backed inventory.
## 4. Reserve capacity
If the source has an active booking-ledger module, hold capacity before finalizing:
```bash theme={null}
curl -X POST "$BASE/inventory-sources/retail-modular/modular/reservations" \
-H "Authorization: Bearer $SCOPE3_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"productId": "avail:sports-week-2026-07",
"mediaBuyId": "mb_123",
"buyerCustomerId": 42,
"requestedImpressions": 250000,
"holdMinutes": 60
}'
```
You can pass either `productId` or `availId`. The reservation prevents this modular source from overbooking against capacity it controls. Upstream booked supply must be removed from `impressionsCapacity` before commit; `upstreamBookedImpressions` is explanatory metadata and does not increase sellable capacity.
## 5. Prepare supported execution handoffs
Execution is module-specific. In the current Cadent demo path, the handoff requires an active booking ledger and an active Cadent execution module. It keeps the reservation `HELD`, renders the Cadent campaign XML, and creates source-side work items for trafficking, creative mapping, and reporting. Do not treat the line as upstream-booked until the trafficking step succeeds; completing the `TRAFFIC_TO_CADENT` work item moves the held reservation to `BOOKED`.
```bash theme={null}
curl -X POST "$BASE/inventory-sources/talpa-cadent-demo/modular/bookings/finalize" \
-H "Authorization: Bearer $SCOPE3_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mediaBuyId": "mb_123",
"availId": "sports-week-2026-07",
"campaignName": "July CTV sports",
"advertiserName": "Example Advertiser",
"creative": {
"format": "video",
"durationSeconds": 30,
"assetUrl": "https://assets.example.com/creative.mp4"
}
}'
```
For a source that books through a person rather than an execution API, the same lifecycle should surface a human work item instead of pretending the stage is automated.
## 6. Release capacity
Release a held reservation when a buyer cancels, a hold expires, or the execution handoff fails:
```bash theme={null}
curl -X POST "$BASE/inventory-sources/retail-modular/modular/bookings/release" \
-H "Authorization: Bearer $SCOPE3_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mediaBuyId": "mb_123",
"availId": "sports-week-2026-07"
}'
```
Removing your storefront from the modular-source pilot does not cancel or
delete lifecycle state. Existing `HELD` reservations continue to reduce
available capacity until they expire or are released through this operation;
`BOOKED` reservations remain booked. Open source-side work items and pending
reports keep their current status and history. Disabling pilot access prevents
new modular-source interactions, but it does not represent upstream
cancellation, completed human work, or completed reporting.
## 7. Work the human queue
Some stages are intentionally human-in-the-loop. Common examples:
| Work item kind | When it appears |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `CONFIRM_AVAILS` | An operator must confirm or correct incoming avails before products are shown. |
| `MAP_CREATIVE_REF` | A buyer creative needs a broadcast-system creative ID or trafficking reference. |
| `TRAFFIC_TO_CADENT` | A Cadent campaign payload is ready for a human operator to traffic; completing it books the held reservation. |
| `UPLOAD_FINAL_REPORT` | The campaign has ended and delivery reporting needs a file upload. |
| `RESOLVE_SOURCE_HEALTH` | A module is blocked or misconfigured. |
These work items belong to the inventory source, not the buyer-facing storefront task. The storefront can still expose buyer task status or webhooks while source operators complete the underlying queue.
## Demo profiles and legacy source recipes
The canonical product demo is [Demo Storefront](/v2/storefront/inventory-sources/demo-storefront).
Its versioned, code-owned profiles compose existing modular contracts and are
clearly labeled synthetic. They do not call or claim to emulate a vendor API.
`POST /inventory-sources/modular/cadent-demo` creates or resets a demo-only source with static avails, a booking ledger, and Cadent execution. Use it to test the end-to-end lifecycle, not as a publisher avails ingestion path. Demo source IDs must be `talpa-cadent-demo` or start with `demo-`.
That Cadent-shaped recipe and the FreeWheel sandbox route remain useful
integration-development precedents. They are not the backing data plane for
Demo Storefront and do not turn a vendor sandbox into the canonical demo.
## Related tasks
Inspect lifecycle status, module contracts, setup gaps, and work-item counts
Write non-secret module setup fields