Skip to main content
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. 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. Only a Seller Account can open them. A Buyer Account is refused with a wrong-account error. sourceId comes from search({ "kind": "inventory_source" }).

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

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.

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.