> ## 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. # Record seller product intent > Record which seller product the organization wants to see plans for. This is the only field the route accepts, and it is for the web app. Other storefront settings are written through V3. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml put /storefront openapi: 3.0.0 info: title: Scope3 Storefront API version: 2.0.0 description: >- REST API for partners to manage Seller Accounts, inventory sources, and billing. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.apostra.com/api/v2/storefront` ## Retired for API callers The v2 storefront API is retired for API callers. Use the V3 API: - HTTP: `https://api.apostra.com/api/v3` - MCP: `https://api.apostra.com/mcp/v3` - Docs: https://docs.apostra.com/v3/quickstart servers: - url: https://api.apostra.com/api/v2/storefront description: Production server security: [] tags: - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Storefront description: Manage storefront and inventory sources - name: Storefront Agents description: List and manage registered sales, signals, and outcomes agents - name: Storefront Activity description: Audit log of configuration and inventory changes on the storefront - name: Storefront Billing description: Payout bank details and billing configuration for Seller Accounts - name: MCP description: Model Context Protocol endpoints paths: /storefront: servers: - url: https://api.apostra.com/api/v2 description: Production server put: tags: - Storefront summary: Record seller product intent description: >- Record which seller product the organization wants to see plans for. This is the only field the route accepts, and it is for the web app. Other storefront settings are written through V3. operationId: updateStorefront requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateStorefrontSellerProductIntentBody' responses: '200': description: Record seller product intent content: application/json: schema: $ref: '#/components/schemas/StorefrontResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: UpdateStorefrontSellerProductIntentBody: type: object properties: sellerProductIntent: type: string enum: - LISTING_ONLY - AGENTIC_MEDIA_COMPANY description: >- Record which seller product the organization wants, so the plans it is offered match. It is intent only and never changes the account type; accepting a plan replaces it. required: - sellerProductIntent additionalProperties: false description: >- Request body for recording the seller product the organization wants to see plans for. No other storefront setting is written here; use the V3 tools. StorefrontResponse: type: object properties: storefrontId: type: string description: Surrogate id (BIGINT serialized as string) example: '1234' platformId: type: string description: Public-facing slug example: acme-media name: type: string description: Display name example: Acme Media publisherDomain: nullable: true description: Publisher domain for the storefront's business profile example: acme.com type: string operatorDomain: nullable: true description: Canonical brand domain example: scope3.com type: string brandName: nullable: true description: Brand name from AAO registry example: Scope3 type: string logoUrl: nullable: true description: Logo URL from brand.json type: string logoBackground: description: >- Backdrop the logo is designed for, from brand.json. Null or absent when unknown; the storefront card falls back to a dark tile. nullable: true type: string enum: - dark-bg - light-bg - transparent-bg membershipStatus: nullable: true description: AAO membership tier. Null when the operator has not set a value. type: string enum: - AAO_FOUNDING_MEMBER - AAO_MEMBER - NONE regions: type: array items: type: string description: >- The countries the seller sells in, as in acceptedCountries: ISO 3166-1 alpha-2 codes, WORLDWIDE when it accepts every country, or empty when it names none. acceptedCountries: nullable: true description: >- Operator-confirmed exhaustive country allowlist for brief routing. Null means routing scope has not been confirmed. type: array items: type: string pattern: ^[A-Z]{2}$ acceptsAllCountries: type: boolean description: Whether the operator explicitly accepts briefs from every country. advertisingPolicyDisclosure: type: array items: type: string enum: - brief_acceptance - creative_policy description: >- An AI Business Rules section the seller elects to disclose publicly as Advertising Policies on its listing. description: >- Seller-selected AI Business Rules sections disclosed publicly as Advertising Policies. Empty means no local disclosure. advertisedCountries: type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Standard primary countries advertised by backing AdCP sales agents. Until a pass-through storefront's seller confirms its markets (`marketsConfirmed`), they are part of its assumed markets; afterwards they are not. advertisedChannels: type: array items: type: string description: >- Standard primary channels advertised by backing AdCP sales agents. Until a pass-through storefront's seller confirms its markets (`marketsConfirmed`), they are part of its assumed markets; afterwards they are not. marketsConfirmed: type: boolean description: >- Whether the storefront's channels and countries are its seller's own. True for a managed storefront, and for a pass-through storefront once its seller has saved its markets. False means the Discovery Card shows assumed markets: the storefront's stored values plus its sales agents' declarations. description: nullable: true description: Operator-curated description (overrides brand.json). type: string channels: type: array items: type: string description: ADCP channel codes the storefront offers. website: nullable: true description: Operator-curated website URL (overrides brand.json). type: string subtitle: nullable: true description: >- Short operator-authored tagline, projected by every marketplace channel listing. Null when unset. type: string supportUrl: nullable: true description: >- Operator-curated support/contact URL, projected by every marketplace channel listing. Null when unset. type: string privacyUrl: nullable: true description: >- Operator-curated privacy policy URL, projected by every marketplace channel listing. Null when unset. type: string termsUrl: nullable: true description: >- Operator-curated Terms of Service URL, projected by every marketplace channel listing. Null when unset. type: string discoveryCard: description: >- Canonical buyer-visible storefront identity and coverage. This is distinct from the legacy Business Profile merchandising inputs and seller policies. allOf: - $ref: '#/components/schemas/DiscoveryCard' demandContactName: nullable: true description: Demand contact name. Null when the operator has not set one. type: string demandContactEmail: nullable: true description: Demand contact email. Null when the operator has not set one. type: string operatorDomainVerified: type: boolean description: >- Whether the brand domain has been verified (email match or manual KYC) routingMode: type: string enum: - CHEF - ADAPTER description: >- Which backend function the buyer-facing storefront dispatches to: the Merchandising Agent or an expert-run adapter. adapterProviderType: nullable: true description: >- Expert-run adapter provider when routingMode is `ADAPTER`; null otherwise. type: string enum: - amazon - audiostack - elevenlabs - fal - gemini - google - linkedin - meta - openai - openai_ads - pinterest - reddit - snap - spotify - tiktok - veo adapterSourceKind: nullable: true description: Adapter role when routingMode is `ADAPTER`; null otherwise. type: string enum: - sales - creative - signals - measurement - optimization - composite adapterCredentialMode: nullable: true description: >- Adapter credential mode when routingMode is `ADAPTER`; null otherwise. type: string enum: - BYOK plan: type: string enum: - basic description: Legacy v2 Seller Account plan tier transacting: type: boolean description: >- Deprecated compatibility projection of `!isPaused`; not proof that the storefront currently satisfies readiness. isPaused: type: boolean description: >- Compatibility-named seller intake hold. True blocks discovery, new buys, and buyer edits but does not pause existing delivery. False is neutral; it does not by itself make the storefront live. archivedAt: nullable: true description: >- When the storefront was archived (read-only thereafter). Null for non-archived storefronts. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ displayStatus: type: string enum: - configuring - transacting - archived - neutral - paused description: >- Deprecated stored-control display status. This is never proof that the storefront can transact; use the readiness projection. capabilities: description: >- Effective buyer-facing AdCP capabilities. Product composition derives from merchandising access and ready Source product paths; it is not locked to the legacy configured flag. allOf: - $ref: '#/components/schemas/StorefrontCapabilities' merchandisingEntitled: type: boolean description: >- Whether the Seller Account commercial plan entitles it to Merchandising. This is a server-derived commercial fact, separate from needing a connected source that is ready to supply products your storefront can sell, such as an ad server. listingDistributionEntitled: type: boolean description: >- Whether the Seller Account commercial plan entitles it to Listing + Distribution. This is independent from Merchandising and from the connected sales agent that fulfills the listing. configuredCapabilities: description: >- Persisted operator capability flags before source-topology derivation. Compare this field for declarative writes; `capabilities` is the effective buyer-facing projection. allOf: - $ref: '#/components/schemas/StorefrontCapabilities' setupIntent: description: >- Compatibility record of the reversible signup package choice, or null when none was selected. It is not a behavioral mode: what the storefront exposes is always the derived `capabilities` and its Source treatment. nullable: true type: string enum: - third_party_connect - sell_through_scope3 operatingMode: description: >- The stored account type, Listing or Storefront (display value for the stored operating capabilities). The account type decides what the account can do, not the organization's plan. Null means a legacy account has not selected a mode yet. nullable: true type: string enum: - LISTING_ONLY - AGENTIC_MEDIA_COMPANY operatingCapabilities: description: >- The stored capabilities that record the account type, Listing or Storefront. The account type decides what the account can do, not the organization's plan. Null means a legacy account has not selected a type yet. nullable: true type: object properties: listingSelected: type: boolean enum: - true scope3MerchandisingSelected: type: boolean required: - listingSelected - scope3MerchandisingSelected additionalProperties: false compositionPricing: description: >- Composition pricing settings: fallback pricing percentile plus seller pricing facts. Separate from Scope3 contract/billing rate cards. allOf: - $ref: '#/components/schemas/StorefrontCompositionPricing' rateCardDocument: description: >- Canonical Library Rate card document that supplies the current pricing facts, or null when no Rate card exists. nullable: true type: object properties: materialId: type: string minLength: 1 maxLength: 255 sourceRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - materialId - sourceRevision - updatedAt additionalProperties: false creativeApproval: type: string enum: - auto - manual description: >- Stored operator setting for creative submissions. It applies at Apostra-managed review checkpoints; a connected sales agent or downstream source may enforce additional source-native review. mediaBuyApproval: type: string enum: - auto - manual description: >- Stored operator setting for new media buys. It applies when the storefront exposes an Apostra-managed campaign-approval checkpoint; a connected sales agent or downstream source may enforce additional source-native review. guaranteedOverForecast: type: string enum: - overbook - hold_for_review description: >- Stored operator setting for guaranteed buys on Google Ad Manager sources that ask for more than the ad server forecasts. `overbook` (the default) sends them; `hold_for_review` holds them in the seller's media-buy review before anything is booked. accountApproval: type: string enum: - auto - manual description: >- Stored operator setting for new buyer accounts that no existing seller decision covers. `auto` (the default) accepts them up to `accountMaxAutoAcceptPaymentTerms`; `manual` sends them to the seller's review queue. accountMaxAutoAcceptPaymentTerms: type: string enum: - net_15 - net_30 - net_45 - net_60 - net_90 - prepay description: >- The longest payment terms accepted automatically when `accountApproval` is `auto`. Defaults to `net_60`. capabilitiesLocked: type: boolean description: >- Legacy topology projection: true when the storefront has at least one active ad-server-backed inventory source (`executionType=MANAGED_SALES_AGENT`). Product composition is now Source-derived, so this value does not authorize or lock capability writes. advertiseAsAgent: type: boolean description: >- Derived: true when the Storefront has an active Inventory Source, an active embedded Sales Agent, adapter routing, or an advertised Storefront-owned capability. Every active Source remains behind the buyer-facing Storefront AdCP endpoint, including COMPOSING-only Sources. sellsThirdPartyInventory: description: >- Operator toggle: when true, the storefront also resells third-party inventory from other Apostra storefronts (composition draws from the marketplace in addition to its own sources). When false/absent (default), the storefront sells only its own inventory sources. type: boolean createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Creation timestamp (ISO 8601) updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Last update timestamp (ISO 8601) businessProfile: nullable: true description: >- Operator-supplied business profile captured during Apostra-led setup. Null when the operator has not shared one. allOf: - $ref: '#/components/schemas/BusinessProfile' defaultCurrency: description: >- Seller-confirmed primary settlement currency (ISO-4217). Null until confirmed; required before go-live for consolidated-billing Seller Accounts. Direct sales adapter Seller Accounts run by our expert agents skip settlement-currency readiness checks because Scope3 does not pay the seller on that path. nullable: true type: string paymentCurrencies: description: >- ISO-4217 currencies the Seller Account will be paid in (the payout set). A media buy settles in one of these. Empty falls back to defaultCurrency. The marketplace may additionally accept buyer currencies outside this set via cross-currency FX, converting each source cost to the buyer currency at the platform spot rate. type: array items: type: string required: - storefrontId - platformId - name - publisherDomain - operatorDomain - brandName - logoUrl - membershipStatus - regions - acceptedCountries - acceptsAllCountries - advertisingPolicyDisclosure - advertisedCountries - advertisedChannels - marketsConfirmed - description - channels - website - subtitle - supportUrl - privacyUrl - termsUrl - discoveryCard - demandContactName - demandContactEmail - operatorDomainVerified - routingMode - adapterProviderType - adapterSourceKind - adapterCredentialMode - plan - transacting - isPaused - archivedAt - displayStatus - capabilities - merchandisingEntitled - listingDistributionEntitled - configuredCapabilities - compositionPricing - creativeApproval - mediaBuyApproval - guaranteedOverForecast - accountApproval - accountMaxAutoAcceptPaymentTerms - capabilitiesLocked - advertiseAsAgent - createdAt - updatedAt - businessProfile additionalProperties: false description: Storefront configuration response ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response DiscoveryCard: type: object properties: storefrontId: type: string platformId: type: string storefrontKind: type: string enum: - managed - external_pass_through displayName: type: string logoUrl: nullable: true type: string logoBackground: nullable: true type: string enum: - dark-bg - light-bg - transparent-bg description: nullable: true type: string website: nullable: true type: string brandColors: nullable: true type: object additionalProperties: type: string channels: type: array items: type: string description: >- Aggregate channel facets for search and display. Do not combine these with aggregate countries as a cross-product coverage promise. countries: type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Aggregate ISO 3166-1 alpha-2 country facets for search and display. Do not combine these with aggregate channels as a cross-product coverage promise. acceptsAllCountries: type: boolean description: >- True only when the storefront explicitly accepts briefs from every country. coverageDeclarations: type: array items: type: object properties: channels: type: array items: type: string description: Channels accepted by this correlated source declaration. countries: type: array items: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 countries accepted by this correlated source declaration. acceptsAllCountries: type: boolean description: >- True only when this correlated source declaration explicitly accepts every country. required: - channels - countries - acceptsAllCountries additionalProperties: false description: >- One source-level coverage claim. Channels and countries are correlated within this declaration; an empty dimension is unknown, not unrestricted. description: >- Channel and country coverage claims preserved at their source boundaries. A combined filter matches only when one declaration satisfies both dimensions. advertisingPolicies: nullable: true type: string maxLength: 10000 coverage: type: object properties: channels: type: string enum: - declared - partial - unknown countries: type: string enum: - declared - partial - unknown required: - channels - countries additionalProperties: false provenance: type: object properties: identity: type: object properties: displayName: type: string enum: - operator - registry - upstream_capabilities - unknown logoUrl: type: string enum: - operator - registry - upstream_capabilities - unknown description: type: string enum: - operator - registry - upstream_capabilities - unknown website: type: string enum: - operator - registry - upstream_capabilities - unknown brandColors: type: string enum: - operator - registry - upstream_capabilities - unknown required: - displayName - logoUrl - description - website - brandColors additionalProperties: false coverage: type: object properties: channels: type: string enum: - operator - registry - upstream_capabilities - unknown countries: type: string enum: - operator - registry - upstream_capabilities - unknown required: - channels - countries additionalProperties: false advertisingPolicies: type: string enum: - operator - registry - upstream_capabilities - unknown required: - identity - coverage - advertisingPolicies additionalProperties: false required: - storefrontId - platformId - storefrontKind - displayName - logoUrl - logoBackground - description - website - brandColors - channels - countries - acceptsAllCountries - coverageDeclarations - advertisingPolicies - coverage - provenance additionalProperties: false description: >- Canonical buyer-visible storefront identity, coverage declaration, and optional Advertising Policies disclosure. Unknown coverage never means worldwide or all channels. StorefrontCapabilities: type: object properties: offersCreativeReview: default: false description: >- Surfaces the creative review protocol surface to buyers. `sync_creatives` returns review-status fields; inline creatives in `create_media_buy` / `update_media_buy` flow through the storefront review gate. The operator policy (auto-approve vs manual queue) is separate config — this flag only governs whether the capability is advertised. type: boolean offersCampaignApproval: default: false description: >- Surfaces the campaign approval protocol surface to buyers. `create_media_buy` and material-change `update_media_buy` may return a submitted-task envelope until the operator decides. The operator policy (auto-approve vs manual queue, material-change threshold) is separate config. type: boolean offersProductComposition: default: false deprecated: true description: >- Read-only compatibility projection. True only while the customer has merchandising access and at least one active Source has a ready Storefront-built product path (`WHOLESALE`). type: boolean required: - offersCreativeReview - offersCampaignApproval - offersProductComposition additionalProperties: false description: >- Which AdCP capabilities the storefront advertises to buyers. Product composition is derived from Source product-path readiness and entitlement. StorefrontCompositionPricing: type: object properties: targetPercentile: default: p75 type: string enum: - p50 - p75 - p90 description: >- Deprecated. Historical auction-clearing percentile, retained for explainability only — it no longer sets the price. Pricing is value-led: the Merchandising Agent prices each brief to its value, bounded by wholesale floors and seller ceilings, never anchored to a clearing percentile. rateCard: default: facts: [] description: >- Seller product-pricing facts. Separate from Scope3 contract rate cards. type: object properties: currency: description: >- Default ISO 4217 currency for pricing facts in this Seller Account rate card. example: USD type: string minLength: 3 maxLength: 3 facts: default: [] maxItems: 500 type: array items: $ref: '#/components/schemas/StorefrontPricingFact' required: - facts additionalProperties: false required: - targetPercentile - rateCard additionalProperties: false description: >- Storefront composition pricing settings: fallback guidance percentile plus lightly structured seller pricing facts. BusinessProfile: type: object properties: summary: description: >- One-paragraph natural-language summary of the business (e.g. "30 properties across web, mobile, and CTV, primarily UK, sports and entertainment focus"). type: string maxLength: 2000 agentName: description: >- Deprecated agent-name field, kept for legacy compatibility only. Prefer the Storefront display name for buyer-facing naming; do not use this to create a separate persona. type: string minLength: 1 maxLength: 80 agentPersonality: description: >- 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; pass null to remove an existing legacy value. type: string minLength: 1 maxLength: 1000 propertyCount: description: Approximate number of owned properties / domains. type: integer minimum: 0 maximum: 10000 channels: description: >- Channels the operator sells across — the full AdCP MediaChannel vocabulary (e.g. display, olv, ctv, social, streaming_audio, dooh, ...), plus the legacy `audio`/`video` aliases. maxItems: 22 type: array items: type: string enum: - display - olv - social - search - ctv - linear_tv - radio - streaming_audio - podcast - dooh - ooh - print - cinema - email - gaming - retail_media - influencer - affiliate - product_placement - sponsored_intelligence - audio - video description: Channel. regions: description: >- The countries the business sells in. Reads list ISO 3166-1 alpha-2 codes, or WORLDWIDE for every country. Writes also take country groups such as EMEA; a value different from what a read shows is saved as acceptedCountries. example: - GB - FR maxItems: 64 type: array items: type: string pattern: ^[A-Z0-9_-]{2,32}$ verticals: description: Topic/vertical focus areas, free-text. example: - sports - entertainment maxItems: 32 type: array items: type: string minLength: 1 maxLength: 80 publisherDomains: description: >- Publisher domains/properties the Merchandising Agent should be authorized to sell through this Storefront. Omit when unknown; omission does not mean all domains are authorized. Domains are normalized to lowercase and deduplicated. example: - pitchside.co.uk - football.pitchside.co.uk maxItems: 128 type: array items: type: string maxLength: 253 pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ evidenceUrls: description: >- URLs the operator pointed Apostra at (media kits, about pages, etc.) so a future conversation can re-read the source material. New values must use HTTP(S). maxItems: 16 type: array items: type: string maxLength: 2048 format: uri notes: description: >- Free-form Apostra-captured notes that did not fit into the structured fields. type: string maxLength: 4000 updatedBy: description: >- Identifier of the agent or user that last wrote this profile (e.g. "murph" or a userId). Audit-only. type: string maxLength: 120 additionalProperties: false description: >- Operator-supplied business profile captured by Apostra during storefront setup. ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object StorefrontPricingFact: type: object properties: id: type: string minLength: 1 maxLength: 120 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ description: >- Stable operator-facing id for this pricing fact. Apostra should preserve ids across rewrites when the fact is semantically the same. label: type: string minLength: 1 maxLength: 160 description: Short display label for this pricing fact. example: Rich media packages appliesWhen: type: string minLength: 1 maxLength: 2000 description: >- Natural-language applicability condition. This is intentionally not a rigid product template; the Merchandising Agent uses it as reasoning context. hints: default: {} description: >- Optional structured hints for deterministic matching. Missing hints are fine. allOf: - $ref: '#/components/schemas/StorefrontPricingFactHints' scope: type: string enum: - all_inventory description: >- all_inventory: the fact applies to every product, in its own currency. It needs pricing.currency and no hints. Omit it for a fact scoped by its hints. pricing: $ref: '#/components/schemas/StorefrontPricingFactPrice' strength: default: default type: string enum: - hard_floor - default - guidance description: >- `hard_floor` is a must-not-go-below seller constraint. `default` is the preferred value-pricing anchor. `guidance` is advisory context only. documentReference: description: >- Immutable Library rate-card row and Material revision that supplied this fact. type: object properties: materialId: type: string pattern: ^mat_[a-z0-9]{12,40}$ sourceRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 rowIndex: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - materialId - sourceRevision - rowIndex additionalProperties: false provenance: description: >- Where this pricing fact came from, such as "Uploaded 2026 rate card, page 3" or "Operator statement on setup call". type: string maxLength: 500 notes: description: Human-readable rationale or caveats for operators and Apostra. type: string maxLength: 2000 required: - id - label - appliesWhen - hints - pricing - strength additionalProperties: false description: >- Lightly structured seller value-pricing fact. Pricing facts anchor prices and floors; they are not product assembly templates. StorefrontPricingFactHints: type: object properties: channels: description: >- AdCP channel codes (e.g. `olv`, `ctv`, `dooh`) this fact applies to. Unlike the free-text hint categories, channels are matched as EXACT codes against the product's seller-declared `channels` plus the broad channel family inferred from its creative format kind — never as substrings of names, ids, or tags. So a fact scoped to `["ctv"]` applies only to products that declare `ctv`; a `video_hosted` format on its own resolves to the broad `video` family, which cannot distinguish `olv` from `ctv`. Within the array any code may match (OR); across hint categories every populated category must match (AND). maxItems: 32 type: array items: type: string minLength: 1 maxLength: 80 creativeTerms: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 120 publisherDomains: maxItems: 128 type: array items: type: string maxLength: 253 pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ countries: maxItems: 64 type: array items: type: string pattern: ^[A-Z0-9_-]{2,32}$ advertiserVerticals: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 120 seasonality: maxItems: 32 type: array items: type: string minLength: 1 maxLength: 120 signalTags: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 120 placementTags: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 120 formatDimensions: description: >- Creative dimensions this fact applies to. A fact matches when at least one pair is admitted by a selected canonical format option: an exact width/height pair must equal it, sizes[] must contain it, and min/max bounds must include it. Unselected options on the same inventory bundle do not count. Within the array any pair may match (OR); across hint categories every populated category must match (AND). maxItems: 64 type: array items: type: object properties: width: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 height: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - width - height additionalProperties: false additionalProperties: false description: >- Optional best-effort hints for matching a seller pricing fact. These are not product assembly rules; the Merchandising Agent still reasons over the natural-language appliesWhen field. StorefrontPricingFactPrice: type: object properties: pricingModel: default: cpm description: >- AdCP pricing model this pricing fact anchors, sourced from the AdCP SDK vocabulary. A price shape the protocol has no model for — share of voice, a day-part premium — is a product-coverage gap to report, not a value to store. type: string enum: - cpm - vcpm - cpc - cpcv - cpv - cpp - cpa - revenue_share - flat_rate - time currency: description: >- ISO 4217 currency for this pricing fact. Falls back to the Seller Account pricing currency when omitted. example: USD type: string minLength: 3 maxLength: 3 targetPrice: description: >- Preferred value-based buyer-facing price for this fact. This is a value anchor, not a cost-plus markup. type: number minimum: 0 exclusiveMinimum: true floorPrice: description: >- Hard minimum buyer-facing price when this fact applies. Composition also floors at wholesale cost/floor. type: number minimum: 0 ceilingPrice: description: Optional maximum buyer-facing price when this fact applies. type: number minimum: 0 exclusiveMinimum: true required: - pricingModel additionalProperties: false description: >- Value-pricing anchor extracted from seller rate cards, media kits, or operator instructions. securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.