Storefront

Deprecated. This page documents the v2 storefront API, which is being retired for external callers. Use Read and configure Seller identity in V3 instead.

Overview

Your storefront is your buyer-facing home on Apostra: the business presence, name, and discovery surface buyers use to understand who they are buying from. Behind it, the Storefront agent answers buyer briefs, composes products, and runs the AdCP media-buy workflow on your behalf, drawing from one or more inventory sources you connect. This page is the operator’s map of the storefront object. Each domain below has its own task pages; this overview explains what the pieces are and how they fit together.

Merchandising is open beta. Every media company can use it — there is no cohort to be admitted into and nothing to apply for. It is beta rather than generally available because the journey is newly built and we have not yet watched enough publishers through it to promise it won’t break. The capabilities inside it keep their own maturity, and any step a person does by hand is marked as such rather than described as automatic.Running real-money campaigns on your own inventory is limited to named companies. The no-spend sandbox — build, activate and read a campaign against your own storefront — is open to every media company. On a storefront connected to an ad platform through an adapter (Google Ad Manager, Meta, LinkedIn, Amazon and the others), the sandbox refuses a buy rather than sending it, because the adapter would create a real order. The same workflow with live spend is switched on for named companies while it is proven, and for those companies live campaigns are read-only in the campaigns experience; changes go through the agent rather than a native write path.

The left navigation opens with one switch that has three modes: Storefront, Managed campaigns, and Settings. Choose a mode and the navigation below the switch lists only that mode’s destinations. The switch replaces the five workspace tabs earlier versions showed (Inventory, Advertisers, Buyers, Agents, and Sessions). Every destination those tabs held is still reachable, except Agents, which now lives in your Developer account (see Agents). A storefront on a Listing plan sees two modes, Storefront and Settings, because the hosted Storefront agent that runs campaigns for advertisers comes with the Storefront agent plan. Managed campaigns appears when your plan includes the Storefront agent, and follows the plan if it changes.

Storefront is where you run the storefront. It groups destinations by what you are doing, and one group is open at a time:

Inventory sources lists each source you have connected, with its setup or health state, and the action to add another.
Your storefront holds what you present and sell by: your storefront’s identity and how it is distributed, your business rules, your buyers, and your Demo Storefront when you have one.
Storefront agent holds what you teach the Storefront agent and package from: your library or product marketing, inventory components, signals, and playbook. Which of these appear, and which show a requirement instead, depends on your plan and your connected sources. A Training section below them holds the tools for teaching and testing your agent: Interview, with a See sessions link to your conversations in Sessions, and the Simulator.
Operate holds the day-to-day work: Sessions (where your account has them), approvals and operations, media buys, seller analytics, and activity. Sessions appears here once as the operational record of buyer exchanges and conversations; it is not a Storefront agent destination.

New chat sits at the bottom of the navigation in this mode. Setup progress stays at the top of Storefront. Beside the status chip (for example Setting up or Live) a count of required steps shows how many you have finished. Select the count to open the full setup checklist. The navigation itself no longer lists company-setup rows or a final-validation row; the places you return to after setup, such as business rules and buyers, sit in Your storefront. Before your storefront goes live, each inventory source in the navigation shows its setup state. A source that is waiting on you names the step to take: Add products, Add credentials, or Add product discovery support. It does not show progress, because nothing is running until you act. A source partway through catalog mapping shows how many items are mapped, for example 4/6. Once the storefront is live, these setup states retire and the navigation shows only problems that need attention. Seller analytics is in Operate.

Managed campaigns

Managed campaigns is for the advertisers you run campaigns for. It uses the same advertiser tools buyers use, scoped to the advertisers your storefront operates. It opens on your sole visible advertiser automatically. When you have several, it reopens the advertiser you last selected for this account; when there is no earlier choice (or no advertisers), it shows the account name and advertiser count. This choice survives a reload and is kept separately for each person and account. Sandbox remains a toggle-revealed badge, not a lens, and the visible set after that toggle determines the default. A link that already names an advertiser always takes precedence. The navigation has a fixed picker with that advertiser’s class, recent selections, search, and All advertisers to return to the overview. Below it are only that advertiser’s jobs. A House or Self-serve advertiser offers Overview, Campaigns, Creatives, and Reporting. Its Overview opens that advertiser’s scoped Campaigns Page. A System advertiser offers read-only Overview, opening that System row’s read-only roster detail. Overview always keeps the selected advertiser scope; only All advertisers returns you to the full roster. When you select a System advertiser, its filtered roster detail stays in the canvas until you choose one of its available jobs; you will not be taken to Campaigns. Your buyers are not in this mode; they are under Buyers in Storefront (below). Each advertiser carries one of three classes — House, Self-serve, or System — shown as a small leading icon. House and Self-serve are advertisers you operate (Self-serve means a client runs their own workflow inside your roster, but you can still edit). Open an advertiser’s settings from the pencil beside it in the picker: a House or Self-serve advertiser shows its status, its details, and Client access, where you invite someone from the client and approve what they can do. System is an Apostra-operated reviewer or compliance-canary advertiser. It is always read-only to the seller and takes precedence over every other class. The class comes from its provisioning record, never its name. When you open All advertisers, the chips above the list (All, House, Partner-managed, Self-serve, System and Needs you) show how many advertisers fall in each group across your whole roster, even when the list below shows only the first 500 matches. Selecting a chip asks the server for that group, and Show sandbox adds your sandbox advertisers to the list and to the counts. A number with a trailing + is a lower bound: a source of advertisers was cut off, so the real count is at least that high. Needs you counts only advertisers whose setup is waiting on your decision. An advertiser waiting on the buyer for information, or held for billing, is not in that count, because you have nothing to do yet. The same rule drives the Needs you count in the navigation and the needs-setup count on each group chip of the organization Advertisers list.

Buyers

To see your buyers, choose Buyers under Your storefront in Storefront. Each buyer reached through an AdCP account relationship appears in its picker, and a buyer whose setup case is waiting on you shows Awaiting you and counts toward the picker’s attention badge. Buyer Account Mapping is always at the top of the list. Selecting a buyer adds that relationship’s jobs:

Sessions, where available, opens the conversation and RFP timeline filtered to that buyer.
Media buys with you opens the buyer’s approval queue and active buys with you.
Creatives synced to you opens the buyer’s synced creative state.
Delivery on your inventory opens delivery for that relationship. It stays unavailable until the buyer is admitted.
Account opens the relationship’s account-setup case: its billing path, setup requests, and inventory mappings.

A buyer’s jobs never open the buyer’s own campaign container. A House or Self-serve advertiser opens Sellers, Activity, Campaigns, Creatives, Catalogs, Conversions, and Reporting — there is no Account job for these, since there’s no relationship or setup case behind an advertiser you operate. System advertisers expose no mutation or navigation affordance. The shared_default billing binding is a billing route, not an advertiser, and is not a seller roster row. A buyer’s account setup can be Needs setup — waiting on you, Waiting on buyer, or Awaiting billing while action remains. A buyer awaiting your decision is reviewed from its Account job or from Buyer Account Mapping; there is no separate inbound-requests list. On a storefront whose sales agent manages buyer accounts, the agent decides instead and the Buyers view is read-only; see When your sales agent manages accounts. Buyer account setup does not change storefront health or the storefront’s go-live status. See Buyer Account Mapping for each state, who acts, and the case action; House, Self-serve, and System advertisers do not carry a setup state.

Settings

Settings is its own mode, not a row at the bottom of the navigation. Choose it to open your account settings in place of the storefront destinations: account and organization settings, plan and billing, API keys, and each advertiser’s Setup & readiness. Choose Storefront or Managed campaigns to return. See Settings in place for what the settings contain.

Agents and the Developer account

Agents are not in the seller navigation. You manage them from your organization’s Developer account: switch to it with the account switcher, and it opens on the Agents page. See Agents for the ownership and navigation model.

Storefront                                  (your buyer-facing surface)
  ├── Business Profile                       (identity, positioning, authorized domains)
  ├── Discovery                              (brand-derived card and publication visibility)
  ├── Operating Instructions                 (versioned guidance; exactly one active)
  └── Inventory Source(s)                    (AdCP agent — discovery + execution)
        └── Buyer accounts                   (the buyers that transact through the source)

All examples use the storefront base URL and a bearer token:

https://api.apostra.com/api/v2/storefront

curl https://api.apostra.com/api/v2/storefront/readiness \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Discovery publication

The listing (previously called the media kit or Discovery Card) is the storefront’s canonical buyer-visible identity and coverage summary. Seller admins publish it from Storefront settings → Discovery by choosing a visibility and selecting Publish. Name, description, website, logo, colors, and generated icons are derived from the storefront card and its brand.json profile, so there is no second directory profile to maintain. Customer 1 can also activate the platform-managed public origin at api.apostra.com; other customers remain limited to private or Apostra visibility during the initial rollout. OpenAI verification is optional and appears only after that public origin is active. See Publisher domains for public routes, verification, and withdrawal behavior.

Inventory sources

An inventory source is private upstream supply behind your storefront. It can be an AdCP-compatible agent, an ad-server connection, a runtime link to another storefront, or a modular lifecycle. Each path supports the product discovery (get_products) and media-buy execution (create_media_buy) stages it advertises. A storefront can use multiple sources, and the products buyers see are assembled from the supply they provide. Sources come in a few shapes:

External sales agents you already run, connected by endpoint and auth.
Managed ad servers — Google Ad Manager, FreeWheel, SpringServe, or AdsWizz — where Apostra runs the sales-agent plumbing in front of your ad server.
Other storefronts that have authorized passthrough or federation.
Modular sources assembled from catalog/avails, booking, creative, execution, reporting, and human-work modules.

Use Choose how your storefront gets supply before connecting anything. It also explains the separate storefront-adapter path, which configures the storefront dispatcher rather than adding an inventory source. Each source declares its capabilities (products, createMediaBuy, updateMediaBuy, signals, wholesaleProducts) and whether it requires authentication. A Storefront-built storefront assembles products across active sources; an Agent-supplied storefront proxies get_products to one upstream source and overlays your storefront identity and buyer instructions on the response.

Business profile

Your business profile is captured during storefront setup and helps the Storefront agent describe your business, follow the right merchandising guidance, and understand which publisher domains it is authorized to sell through the storefront.

Field	Type	Description
`summary`	string	Concise explanation of what the storefront sells. Maximum 2000 characters.
`agentName`	string	Deprecated agent-name field, kept for legacy compatibility only. Prefer the storefront display name for buyer-facing naming. Maximum 80 characters.
`agentPersonality`	string	Deprecated. An agent has no personality of its own — voice belongs to the brand and is read from the brand manifest (`tone`). Nothing consumes this field. Maximum 1000 characters.
`propertyCount`	integer	Approximate number of owned publisher properties, from 0 to 10,000.
`channels`	string[]	The full AdCP MediaChannel vocabulary the storefront offers: `display`, `olv`, `social`, `search`, `ctv`, `linear_tv`, `radio`, `streaming_audio`, `podcast`, `dooh`, `ooh`, `print`, `cinema`, `email`, `gaming`, `retail_media`, `influencer`, `affiliate`, `product_placement`, or `sponsored_intelligence`. The legacy aliases `audio` (for `streaming_audio`) and `video` (for `olv`) are also accepted on write and round-trip unchanged.
`regions`	string[]	Up to 64 ISO alpha-2 country codes or region groups such as `EMEA` and `WORLDWIDE`.
`verticals`	string[]	Up to 32 audience or content focus areas, each no more than 80 characters.
`publisherDomains`	string[]	Publisher domains or properties the storefront is authorized to sell. Up to 128 valid domains; each is normalized to lowercase, deduplicated, and limited to 253 characters.
`evidenceUrls`	string[]	Up to 16 media-kit, about-page, or other source URLs.
`notes`	string	Confirmed context that does not fit the structured fields. Maximum 4000 characters.
`updatedBy`	string	Audit marker for the last writer. The Business Profile page manages this automatically.

Regions are retired; your markets are your countries. See Seller markets.

Example

{
  "businessProfile": {
    "summary": "Premium sports inventory across web, mobile, and CTV.",
    "channels": ["display", "ctv"],
    "publisherDomains": ["touchline.example", "football.touchline.example"]
  }
}

Omitting publisherDomains means the authorized domains are unknown or have not been captured yet. It does not mean the storefront is authorized to sell every domain.

In an MCP-compatible assistant, call get_business_profile to open the portable Business Profile page. Operators can review, create, and edit the profile in the page. An assistant can also call update_business_profile for an exact change confirmed in conversation. That tool applies a patch: omitted fields from the profile state read for that call stay unchanged, while an explicit null clears a field. Overlapping patch calls use last-writer-wins behavior, so clients should serialize concurrent edits. For managed sales-agent storefronts, this field is the authoritative publisher-domain set Apostra syncs to the managed sales agent. See Publisher domains for replacement and removal behavior.

Operating instructions

Operating instructions are versioned guidance that steers how your storefront responds to demand — what to package, how to position, and how to negotiate. Exactly one version is active at a time; publishing a new version supersedes the prior one without losing history. Operating instructions are authoritative over historical analytics signals. When the Storefront agent composes products, your written instructions and buyer instructions win over any directional signal derived from recent outcomes.

Readiness diagnostics

GET /readiness tells you whether your storefront can transact now. It returns blocking checks for inventory sources, agent status, and agent auth, plus a per-source sourceDiagnostics[] array used by setup surfaces. The overall status is ready or blocked; each check reports complete, partial, missing, or optional, and carries an isBlocker flag. Storefront lifecycle is not stored as a state. The seller-owned control is the buyer intake hold, exposed under the released compatibility name isPaused. It defaults to false. Setting it to true removes products from buyer discovery and blocks new media buys and buyer edits. Seller preview still works, and an approved buy that has not yet been sent to a source waits in the queue and forwards automatically after intake resumes. Clearing an intake hold is always available unless the storefront is archived: it restores the seller’s prior neutral intake posture without claiming that a new readiness, runtime-safety, or administrative requirement has passed. Those independent safeguards continue to determine whether new business can actually transact. An intake hold does not pause campaigns already delivering in your ad server. Existing campaigns keep delivering and reporting. A storefront-wide delivery freeze is a separate, confirmed operation because resuming it must not activate campaigns that were already paused before the freeze. Effective status remains the v2-compatible archived, paused, blocked, or live. A storefront without an intake hold becomes live automatically when every current requirement passes, and becomes blocked automatically when any new or existing requirement fails. The deprecated transacting field is only an API compatibility projection of !isPaused; it is not proof of readiness. See Get readiness for the full field reference.

Apostra review and AAO signals

New storefronts start in a pending-review state. You can configure and use your storefront, and open it for known transactions, but public buyer discovery only includes storefronts that Apostra has reviewed and listed. Listing on Apostra uses signals from the Agentic Advertising Organization (AAO) registry. Source registration, storyboard compliance, and publisher authorization are different checks: registration blocks connecting an external agent source; compliance is advisory for activation; publisher adagents.json authorization is surfaced as an advisory setup/product signal today. Apostra’s review decides when a live storefront is listed in public buyer discovery. Use Discover agents and Resolve brand to inspect what the registry knows about your brand domain and the brands you transact with.

An admin can hide a listed storefront, which removes it from public buyer discovery without deleting the storefront or its inventory sources.

Storefront domains

Inventory sources

Connect and manage the AdCP agents and ad servers behind your storefront.

Operating instructions

Versioned merchandising and negotiation guidance.

Signals

The targeting and optimization inputs your sources expose.

Media-Buy Approvals

Review and decide on incoming media buys before they go live.

Billing

Payout bank details and fees so Apostra can pay you.

Analytics

Win rate, buyer asks, top products, and negotiation posture.

Buyer instructions

Per-buyer discounts, notes, and country scoping.

Start here

Buy media

Sell media

Help and updates

Storefront

Overview

Seller navigation

Storefront

Managed campaigns

Buyers

Settings

Agents and the Developer account

Discovery publication

Inventory sources

Business profile

Operating instructions

Readiness diagnostics

Apostra review and AAO signals

Storefront domains

Inventory sources

Operating instructions

Signals

Media-Buy Approvals

Billing

Analytics

Buyer instructions

​Overview

​Seller navigation

​Storefront

​Managed campaigns

​Buyers

​Settings

​Agents and the Developer account

​Discovery publication

​Inventory sources

​Business profile

​Operating instructions

​Readiness diagnostics

​Apostra review and AAO signals

​Storefront domains

Inventory sources

Operating instructions

Signals

Media-Buy Approvals

Billing

Analytics

Buyer instructions

Overview

Seller navigation

Storefront

Managed campaigns

Buyers

Settings

Agents and the Developer account

Discovery publication

Inventory sources

Business profile

Operating instructions

Readiness diagnostics

Apostra review and AAO signals

Storefront domains