Skip to main content
Deprecated. This page documents the v2 storefront API, which is being retired for external callers. Use Add and diagnose inventory in V3 instead.
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 Apostra-managed sales-agent plumbing behind it (an ad-server-backed source), a linked storefront source, or a modular source assembled from individual modules. Buyers never target a source directly — they call your storefront, and discovery fans out to every eligible, compatible Source. All examples use the storefront base URL:
Authenticate ordinary storefront requests with Authorization: Bearer $SCOPE3_API_KEY. The storefront is resolved from your API key’s account context — there is no customerId path parameter. Routes below that explicitly require a direct human Account Admin or SuperAdmin session use that session instead.

​
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, SpringServe, or AdsWizz), LINKED_STOREFRONT, or MODULAR_SOURCE. AGENT sources use the generic inventory-source endpoints. A pilot-enabled seller can use the same create endpoint to create a linked storefront source that selects an approved storefront as LINKED_STOREFRONT; the new row remains PENDING, cannot receive requests or bookings, and can only be disabled until its separate terms and activation requirements are met. Managed and modular sources use dedicated provisioning 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 → ACTIVE. That source status is the single lifecycle authority for an external-agent source; its connection metadata and legacy agent registration do not carry a second status. An external-agent source served by a registered Sales Agent can move to ACTIVE once that Agent’s connection passes its authorization, validation, health, and commercial checks. When another organization owns the Agent, the Agent must also have passed live certification (How certification works); a source served by your own organization’s Agent does not need it. Until the remaining connection gates pass, an activation request is refused with 409 CONFLICT (reason agent_connection_not_ready) and the source stays in its current status. AAO compliance is a separate, advisory signal and does not gate this step. Check the connection on the source’s diagnostics, then activate the source again. Production certification remains a Partner Program readiness requirement when an Agent is offered to other organizations. A linked storefront source starts PENDING; configure its pass-through terms and activate it when the selected partner storefront still consents. A failed activation keeps the current status: PENDING stays PENDING, and DISABLED stays DISABLED. You can update terms while it is pending, active, or disabled. Updating disabled terms leaves it disabled; activate it separately to use the latest terms version. Archived linked storefront sources cannot be configured. You can disable a linked storefront source with the standard update endpoint. Existing diagnostics may still return agentStatus as a deprecated copy of sourceStatus; do not interpret it independently. An ad-server-backed source is enabled unless deactivatedAt is set (null means enabled). Its operational.isLive value is health/readiness presentation, not a discovery-eligibility decision. 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.
  • Linked storefront source terms. The pilot uses pass-through terms: the buyer price equals the partner price, the platform retains 0%, and supplier settlement is external to the platform. The buyer-payment collector comes from the buyer account’s approved billing setting for the selected seller account on your storefront and is recorded on each booking. This is separate from the partner’s consent for your storefront to buy from it. Changing terms creates a new version; a later activation uses the latest version, while existing bookings keep the terms recorded when they were booked. For flag-enabled pilot storefronts, active linked storefront sources with current partner consent receive briefs and bookings. Pending, disabled, archived, or no-longer-authorized sources do not. The partner sees your storefront as the buyer for these requests; your buyer’s account remains on your own booking and is not sent to the partner.
  • Linked partner availability. A linked partner must remain listed on Apostra, opted in, unpaused, and unarchived for new briefs, bookings, budget increases, and new packages. If the partner later delists, existing bookings still support delivery reads and polling, cancellation, budget decreases, creative sync, and approval forwarding for as long as that partner storefront exists. A delisted partner cannot receive new work.
  • Eligibility is not health. Apostra sends discovery to every Source whose Storefront and Source setup are complete, whose Storefront is not paused, and whose Source and mapped Agent are explicitly eligible. Request channel, country, and currency compatibility then selects the recipients for that request. Degraded or erroring health remains visible but does not stop requests by itself; an explicit ineligibility decision does.
  • Product paths. A Sales Agent explicitly declares whether it supplies ingredients for Apostra to merchandise (Storefront-built), complete buyer-ready products (Agent-supplied), or both. A Source whose Agent supports both selects one or both paths. This is not a separately priced add-on and is not controlled by a Storefront-wide toggle.
  • Managed sources are wholesale. An ad-server-backed source has a fixed Storefront-built contract because raw ad-server inventory must be converted into sellable products. Other active Sources retain their own independent paths.
  • Component cache. When a Storefront-built source supports AdCP 3.1+ wholesale products, Apostra stores those inputs for merchandising and Storefront-built 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.
  • Connection definitions are versioned. The external sales-agent Task pins the endpoint, protocol, and authentication definition used during setup. Built-in and Partner-backed integrations use the same typed definition model, while older integrations keep their existing setup path until migrated.
  • 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.

​
Plans, entitlements, and feature profiles

Inventory Sources is available in the navigation for every seller account. A new seller chooses Just list or Agentic Media Company. Both include listing and can connect inventory through the supported source paths. Just list uses an agent operated by your company, a partner, or another provider; that agent can be connected during setup and does not need to exist at signup. Agentic Media Company adds Apostra’s hosted Merchandising Agent, which you train for your business. Operator ownership is Source configuration, not a separate plan or feature profile. Plans are the commercial choice. Each plan declares its default feature profile. Feature profiles determine the coherent set of product surfaces the account receives; entitlements are reserved for independently sold additions:
  • Basic / Listing includes Apostra listing, sales-agent connection, and operational surfaces for campaigns, media buys, creatives, approvals, delivery, activity, and reporting. AI Business Rules are available here. Saving, enabling, and evaluating AI Business Rules is not an IU-rated activity today; other qualifying activity remains governed by the organization’s accepted IU Rate Card.
  • Listing + Distribution is the standard paid Seller Account package for unlimited self-serve advertiser invitations and management, public listing distribution and an optional customer CNAME, and customer-branded AdCP and ChatGPT app channels. It does not improve or rank Apostra listing, replace the connected sales agent, or enable Merchandising and modular inventory sources. Existing accepted offers continue to use the advertiser capacity stated in their terms. Until this package is active, Listing shows the Public distribution benefits and an upgrade link instead of the domain step and destination controls.
  • Premium uses the Merchandising profile. Merchandising includes publisher self-service and Custom modular sources without separate entitlements.
Enterprise describes custom commercial terms such as price, term, credits, support, and payment arrangements. It uses the same Premium/Merchandising profile when the product surfaces are the same, so Enterprise also includes publisher self-service and Custom modular sources. A separate Enterprise feature profile is needed only if the account receives a genuinely different product experience—not merely a different contract. Standard managed integrations are included with every seller plan; sellers do not need to know whether Apostra implements one with modular internals. The stable internal feature key for customer-specific composition is modular-sources, and customer-facing surfaces call it Custom modular sources. Basic excludes it; Premium and Enterprise include it through the Merchandising profile. It is not a separately provisioned entitlement.

​
Working with an ad-server source in Apostra

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, Apostra 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 the Inventory workspace in the seller navigation and choose Add inventory source whenever you want to connect another source. This opens the Inventory sources list and expands the provider choices immediately. Choose an ad server, a modular inventory source, or an external AdCP sales agent to open its structured setup flow; the button does not turn the action 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. When an exact specialist destination is available, the source card also shows Open source. It opens the existing ad-server detail, modular readiness, or external-agent diagnostics surface directly. The action is omitted when that destination cannot be resolved or its capability is not enabled.

​
Certify the agent behind a source

Apostra certifies a sales agent on live traffic, use case by use case. It does not ask you to nominate a separate test Source, and staff do not approve a test setup. The certification buy goes through the same Source that carries live buys, on a sandbox account that your agent’s sync_accounts returns. See How certification works. The older request to nominate a certification test fixture is retired. See Submit certification test setup. Seller Setup keeps the decisions separate: setup complete or setup required; Agent unmapped, certified, validated, or unvalidated; context-free routing eligibility; Source health; and Agent implementation health. Use Source Health or TARS to preview whether a Source is selected for an exact channel/country/currency request. A sales agent on the Agent-supplied path does not need a warm merchandising cache. Bad or malformed returned products are a health error and are filtered from the response, but they do not silently make the Source ineligible.
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

List inventory sources

Every source on the storefront

Create inventory source

Register an external AGENT source

Get inventory source

Read one source by ID

Diagnose third-party sales agents

Check source health and recent AdCP activity

Update inventory source

Change fields, rotate auth, transition status

Delete inventory source

Remove a source and disable its agent

​
Ad-server connection

Connect an ad server

Connect a source, or replace its configuration and credentials, through V3

​
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 for the full setup checklist, feed format, sequence, and examples.

Prepare inventory source inputs

Request the complete evidence pack and copy parser-valid avails templates

Modular lifecycle guide

End-to-end avails, reservation, execution handoff, release, and HITL workflow

Author property and tag mappings

Preview and author property/tag to key-value, ad-unit, or placement mappings

Get modular readiness

Runtime projection for a modular source

Update module config

Write non-secret config for one module

All inventory-source tasks

Every operation in one place

Storefront onboarding

End-to-end seller setup

Diagnose third-party sales agents

How to inspect source health and recent ADCP calls

Storefront object guide

How buyers see your storefront

Errors

Shared error contract