Modular inventory source lifecycle

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.

Composing a modular inventory source is an Enterprise capability and currently also feature flagged for pilot exposure. Your account needs both an active modular-source entitlement and pilot exposure to create a source. Existing sources remain visible and operational if the entitlement or rollout exposure is later removed; the restriction applies to new composition, module attachment, and demo resets that replace the source composition.

Storefront MCP clients open the same three portable surfaces with prepare_modular_source, get_modular_inventory_source_readiness, and prepare_modular_avails_commit. The Page and Tasks use named api_call operations for their data and confirmed writes. The operator-facing operation set also includes list_modular_inventory_source_products, get_modular_inventory_capabilities, and search_modular_source_inventory_selectors. Work-item detail, capacity and booking changes, module configuration, and credential entry remain in confirmation-gated trusted Tasks or the operator UI. All examples use the storefront base URL:

export BASE=https://api.interchange.io/api/v2/storefront
export SCOPE3_API_KEY=scope3_<your_api_key>

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. Connecting these managed adapters is included and has no source-count limit.
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. Because that source is still composed from modules, creating it requires the same Enterprise modular-source entitlement even though its dedicated ad-server route is exposed independently of the advanced modular-source pilot flag. The storefront remains in CHEF routing mode; buyers see the storefront, not a CitrusAd adapter or the private module graph. 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:

/inventory-sources/{sourceId}/modular/modules/{moduleInstanceId}/credentials/{credentialKind}

credentialKind is API_KEY, BEARER, or OAUTH. For example:

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": "<provider-user-key>" },
    "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 modular 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 modular 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.
Modular inventory source	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. Every modular 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.

Preview buyer discovery from one source

When Get products is Ready in the Modular inventory source workspace, select Preview buyer discovery. In the Source discovery preview Task, enter a representative buyer brief and select Run preview. The Task shows only products that source would return through your storefront. The preview rechecks that the source is active and Get products is still Ready when you run it. If either check fails, the Task stops and asks you to finish the source setup. It never includes products from another inventory source. The Task records the preview decision for later review. It does not create a media buy, change live products or source setup, or turn on transacting. Brief tests started outside a source workspace remain storefront-wide.

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.
`formatOptions`	Non-empty URL-free AdCP declarations for the collection, using `format_kind` plus canonical `params`.
`publisherProperties`	Non-empty AdCP Property selectors for the collection’s publisher inventory.
`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. Descriptive only; it never determines creative format.
`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:

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.

collectionId,collectionName,availId,name,startTime,endTime,impressionsCapacity,channel,formatOptions,publisherProperties,cpm,currency
publisher-ctv,Publisher CTV,publisher-ctv-2026-07,CTV July,2026-07-01,2026-08-01,150000000,CTV,"[{""format_option_id"":""ctv-vast-30"",""format_kind"":""video_vast"",""params"":{""duration_ms_exact"":30000}}]","[{""selection_type"":""all"",""publisher_domain"":""publisher.example""}]",24.00,USD

Murph walkthrough

Murph should not force a seller into a blank template. A good setup conversation looks like this:

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.
Classify the material. Keep market context as context; do not commit it as avails.
Ask for missing row-level avails if the seller only supplied market scale.
Create the modular source only after the operator confirms the source name and lifecycle plan.
Preview the feed. Show normalized rows and whether capacity is net or gross-minus-booked.
Commit only after explicit confirmation.
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.
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:

curl "$BASE/inventory-sources/retail-modular/modular" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

The response includes lifecycleSummary, one row per stage:

Status	Meaning
`UNSUPPORTED`	Every attached module declared what it covers, and none of them implements this stage. Attach a module of the kind that runs it.
`NOT_DECLARED`	A module that could run this stage is attached, but we could not read what it does — so whether it runs the stage is unknown, not absent. The stage’s `issues` name that module, and `modes` is empty because nothing declared how the stage operates. This is not a setup gap and there is nothing to configure: a module we cannot read is ours to fix. Tell Murph if a stage you depend on reads this way.
`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, INVALID_CANONICAL_FORMATS, INVALID_PUBLISHER_PROPERTIES, and GROSS_CAPACITY_NORMALIZED. The last is a warning that net sellable capacity was calculated by subtracting upstream booked impressions from gross capacity. Formats and properties belong to the stable collection rather than one availability window. Supply formatOptions and publisherProperties on each row, or send defaultFormatOptions and defaultPublisherProperties alongside a JSON preview request. Spreadsheet cells use JSON-encoded arrays. Every row with the same collectionId must repeat the same declarations. The service rejects missing, conflicting, malformed, or URL-bearing declarations and never infers a format from channel.

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",
        "formatOptions": [
          {
            "format_option_id": "ctv-vast-30",
            "format_kind": "video_vast",
            "params": { "duration_ms_exact": 30000 }
          }
        ],
        "publisherProperties": [
          {
            "selection_type": "all",
            "publisher_domain": "publisher.example"
          }
        ],
        "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:

curl "$BASE/inventory-sources/retail-modular/modular/products" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Each product maps back to one normalized avail and returns the collection’s canonical formatOptions and publisherProperties. A collection missing valid declarations fails closed with the typed MODULAR_CATALOG_NOT_READY readiness code before Chef or another model can see it. 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:

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.

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:

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. 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.

Get modular readiness

Inspect lifecycle status, module contracts, setup gaps, and work-item counts

Update module config

Write non-secret module setup fields

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Modular inventory source lifecycle

When to use a modular source

Modules

Module credentials

Seller setup checklist

The three setup surfaces in chat

Preview buyer discovery from one source

Avails feed requirements

Murph walkthrough

1. Check readiness

2. Preview, then commit avails

3. Inspect product projections

4. Reserve capacity

5. Prepare supported execution handoffs

6. Release capacity

7. Work the human queue

Demo profiles and legacy source recipes

Get modular readiness

Update module config

​When to use a modular source

​Modules

​Module credentials

​Seller setup checklist

​The three setup surfaces in chat

​Preview buyer discovery from one source

​Avails feed requirements

​Murph walkthrough

​1. Check readiness

​2. Preview, then commit avails

​3. Inspect product projections

​4. Reserve capacity

​5. Prepare supported execution handoffs

​6. Release capacity

​7. Work the human queue

​Demo profiles and legacy source recipes

​Related tasks

Get modular readiness

Update module config

When to use a modular source

Modules

Module credentials

Seller setup checklist

The three setup surfaces in chat

Preview buyer discovery from one source

Avails feed requirements

Murph walkthrough

1. Check readiness

2. Preview, then commit avails

3. Inspect product projections

4. Reserve capacity

5. Prepare supported execution handoffs

6. Release capacity

7. Work the human queue

Demo profiles and legacy source recipes

Related tasks