> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modular source Pages

> Open the modular_source_setup, modular_inventory_source and modular_inventory_feed Pages from V3 to add a modular source, check its readiness and commit an avails feed.

A **modular inventory source** is an operator-managed source made of smaller
modules: an inventory feed, a booking ledger, and optional execution modules and
human work queues. Use one when your inventory and execution do not come from a
single upstream sales agent. The modules and lifecycle stages are explained in
[Modular inventory source lifecycle](https://docs.apostra.com/v2/storefront/inventory-sources/modular-lifecycle.md).

V3 gives a modular source three Pages. Each has one job. You open them with
`open_page`, and a person completes the work in the Page.

| `open_page.page` | Optional input | What it is for |
| - | - | - |
| `modular_source_setup` | None | **Add a modular source.** Register a new feed-backed source: its name, where its avails come from and how often they arrive. The Page closes when the source is created. |
| `modular_inventory_source` | `sourceId` | **Modular inventory source.** The workspace for an existing source: how ready each lifecycle stage is, which modules are attached, and the source-side work waiting on a person. |
| `modular_inventory_feed` | `sourceId`, `sourceName` | **Commit avails feed.** Preview a supported inventory feed for an existing modular source and commit it once. `sourceName` only seeds the source name the Page shows while it loads. |

Only a Seller Account can open them. A Buyer Account is refused with a
wrong-account error. `sourceId` comes from `search({ "kind": "inventory_source" })`.

```json theme={null}
{ "page": "modular_inventory_source", "sourceId": "SOURCE_ID" }
```

## Availability

Custom modular sources are part of a Premium or Enterprise Storefront Agent plan.
Without them the Pages are refused with `ACCESS_DENIED` and the message
"Custom modular inventory sources require a Premium or Enterprise Storefront Agent
plan." The one exception is a synthetic source attached by the Demo Storefront.
With its `sourceId`, the `modular_inventory_source` Page opens it read-only so you can inspect it.

## What happens in each Page

**Add a modular source** creates a feed-backed source. It does not ask how you
book, traffic, clear creative or report. Those answers come from the modules
attached to the source and appear in the workspace. A new source starts with an
avails-feed module and Apostra's booking ledger.

**Modular inventory source** is the page you return to. Its summary shows
readiness above the fold. Below it are the lifecycle stages, the attached
modules and the source-side work queue. The Page launches the add-source and
avails-feed Pages when you need them.

**Commit avails feed** sends the file straight from the Page to private
storage, so the model never receives the feed's bytes. The Page previews the
rows before you confirm. Creating a source and
committing a feed are explicit, confirmed writes. Nothing is offered to buyers
until avails rows are committed. A source with no committed rows is registered
but has no sellable capacity.

## What you can do from V3 without a Page

The reads and the typed saves below are V3 tools. They work on the same sources
the Pages open.

| Job | V3 call |
| - | - |
| Read a source's module roster and lifecycle coverage | `get({ "kind": "inventory_source", "id": "SOURCE_ID", "include": ["modularReadiness"] })`. A compact `moduleRoster` comes first. |
| Change one module's non-secret configuration | `save_inventory_source` with `moduleConfig` and the module's `moduleInstanceId`. Send `config` as a list of `{ "key", "value" }` entries, for example `[{ "key": "freewheel.autoExecuteBookings", "value": true }]`. Save source fields in a separate call. |
| List the source-side follow-ups | `search({ "kind": "work_item" })`. Modular follow-ups use the states OPEN, IN\_PROGRESS, BLOCKED, COMPLETED and CANCELLED. |
| Complete a follow-up | `save_work_item` with `kind: "modular_source"`, the follow-up `id`, the `sourceId`, `status: "completed"`, and a `result` entry for each field the item names, for example `[{ "key": "upstream.campaignId", "value": "CMP-1" }]`. Never put secrets in `result`. |
| Read what a source offers | `search({ "kind": "wholesale_product", "sourceId": "SOURCE_ID" })`. Its products have `origin: "modular_source"`. |

Both `config` and `result` are lists of entries, not objects. The `key` is the
dotted field key you already read: the readiness view lists the settings that
are present as `configuredFieldKeys`, and a follow-up lists the fields it needs
as `requiredResultFields`. Apostra expands a dotted key into the nested field it
stores, so `freewheel.autoExecuteBookings` sets `autoExecuteBookings` inside
`freewheel`. Send each key once, and never a key and one of its children
together.

A `config` value is a string, a number or a boolean. Settings that Apostra owns
for a connection, such as the CitrusAd namespaces, are not changed here. A
`result` value is a string or a number. It can also be a list of strings, for
`freewheel.creativeInstanceIds`, or a list of daily delivery rows for
`reporting.dailyBreakdown`, each with a `date`, `impressions` and `spend`. Fields
that a module writes itself, such as `citrusad.delivery`, are not sent by the
caller.

The earlier object form of `config` and `result` is deprecated. Apostra still
accepts it for now and stores it as it always did, but send entries.

A modular source's products come from the committed feed. You cannot change
them with `save_wholesale_product`. Upload a new feed instead. See
[Create and manage seller products](https://docs.apostra.com/v3/seller-product-creation.md#which-sources-hold-products-you-can-author).

## Plan a no-spend campaign test

After the source's read-only discovery preview returns the products you expect,
ask Apostra to plan a no-spend test campaign for that modular source. Planning
checks that the exact source and trafficking module are approved for the
protected no-spend path. If that approval is missing, the plan stops before
confirmation and tells you to ask Apostra Support for source-specific approval.
Do not unpause the storefront to work around it.

Planning does not create a campaign, media buy, creative or approval. Review the
source, advertiser, flight, budget and product selections before you confirm
the test. The confirmed run uses debug execution so it cannot spend, and it
does not activate the source, unpause the storefront, publish a Listing or
change one.

A follow-up is addressed by both `sourceId` and `id`, and a completion that
names no source is refused. Saving the same completed result again returns
`unchanged`, and a conflicting correction is refused rather than overwriting the
recorded result. See
[Operate work items and approvals](https://docs.apostra.com/v2/setup/v3/seller-workflows.md#operate-work-items-and-approvals).

## If your plan changes

Downgrading to Basic does not cancel or delete a modular source's lifecycle
state. A held reservation keeps reducing available capacity until it expires or
Apostra releases it because its buy failed or was cancelled. A booked reservation
stays booked. Open follow-ups and pending reports keep their status and history.
The downgrade stops new composition and hides pilot surfaces. It does not
represent an upstream cancellation, finished human work or a finished report.

## What V3 does not cover

V3 has no tool that ingests a feed, lists a modular source's products, or
searches ad-server selectors. Feed ingest goes through the
`modular_inventory_feed` Page. Credential entry stays in the Page and the
operator UI, and no credential passes through a model.

## Related

* [Seller workflows: Add and diagnose inventory](https://docs.apostra.com/v2/setup/v3/seller-workflows.md#add-and-diagnose-inventory)
* [Modular inventory source lifecycle](https://docs.apostra.com/v2/storefront/inventory-sources/modular-lifecycle.md),
  which covers the avails feed format and the lifecycle in detail. It
  describes the v2 storefront API, which is deprecated.
* [Source diagnostics Page](https://docs.apostra.com/v3/seller-source-diagnostics-page.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.