> ## Documentation Index > Fetch the complete documentation index at: https://docs.interchange.io/llms.txt > Use this file to discover all available pages before exploring further. # Create inventory source > Create an inventory source and optionally register an agent for it. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml post /inventory-sources openapi: 3.0.0 info: title: Scope3 Storefront API version: 2.0.0 description: |- REST API for partners to manage storefronts, inventory sources, and billing. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/storefront` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/storefront` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.interchange.io/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 storefronts - name: AI Usage description: Storefront AI token usage visibility by model - name: MCP description: Model Context Protocol endpoints paths: /inventory-sources: post: tags: - Storefront summary: Create inventory source description: Create an inventory source and optionally register an agent for it. operationId: createInventorySource requestBody: required: true content: application/json: schema: type: object properties: connectionContract: description: >- Pinned connection contract used to validate this setup. Omit only for integrations that have not migrated to connection contracts yet. type: object properties: id: type: string minLength: 1 maxLength: 128 pattern: ^[a-z][a-z0-9_-]*$ version: type: integer maximum: 9007199254740991 minimum: 1 authenticationMethod: type: string enum: - none - bearer_token - api_key - credential_exchange - basic_auth - oauth2 - jwt - platform_service_account required: - id - version - authenticationMethod additionalProperties: false sourceId: description: >- Unique identifier for this source within the storefront. Defaults to a slugified version of the name if not provided. example: retail-network-agent type: string minLength: 1 maxLength: 255 name: description: Display name for the inventory source example: Retail Network Agent type: string minLength: 1 maxLength: 255 executionType: description: >- Only external `AGENT` inventory sources can be created through this endpoint. `MANAGED_SALES_AGENT` and `MODULAR_SOURCE` rows are created by their dedicated provisioning flows; `LINKED_STOREFRONT` sources are never created or persisted — storefront interchange is resolved at runtime from the ambient wholesale pool. Storefront-level `ADAPTER` dispatch is configured on the storefront, not as an inventory source. default: AGENT type: string enum: - AGENT type: description: Agent type — required when executionType is "AGENT" type: string enum: - SALES - SIGNAL - CREATIVE - OUTCOME endpointUrl: description: Agent endpoint URL — required when executionType is "AGENT" type: string maxLength: 2048 format: uri protocol: description: Agent protocol — required when executionType is "AGENT" type: string enum: - MCP - A2A authenticationType: description: >- Auth method for the agent — required when executionType is "AGENT" type: string enum: - API_KEY - NO_AUTH - JWT - OAUTH - BASIC_AUTH auth: description: >- Optional for most schemes. NO_AUTH sources need no credentials at all, and OAUTH sources are authorized through their own flow — neither carries an `auth` payload. BASIC_AUTH and API_KEY sources may include credentials here, or be created without them and start PENDING, with the secret collected later through the secure credential form rather than at create time (for BASIC_AUTH use { type: "basic", username, password }). JWT is the exception: its secret must be supplied here at create time, because the secure credential form cannot collect JWT yet. anyOf: - type: object properties: type: type: string enum: - jwt privateKey: type: string minLength: 1 issuer: type: string minLength: 1 subject: type: string minLength: 1 keyId: type: string minLength: 1 scope: type: string minLength: 1 tokenEndpointUrl: type: string format: uri audienceUrl: type: string format: uri algorithm: type: string enum: - ES256 - RS256 environment: type: string required: - type - privateKey - issuer - subject - keyId - scope - tokenEndpointUrl - audienceUrl - type: object properties: type: type: string enum: - bearer - apikey - api_key token: type: string minLength: 1 required: - type - token - type: object properties: type: type: string enum: - basic username: type: string minLength: 1 password: type: string required: - type - username - password - type: object properties: {} additionalProperties: false oauthAudience: description: >- OAuth audience / resource indicator for OAUTH agents (the protected-resource URI the agent gateway validates, e.g. "https://platform.example.com"). When set, the OAuth flow requests a token whose `aud` claim targets this resource (sent as both Auth0 `audience` and RFC 8707 `resource`). Leave unset to auto-discover it from the agent's RFC 9728 protected-resource metadata. example: https://platform.example.com type: string maxLength: 2048 format: uri description: description: Agent description type: string maxLength: 2000 required: - name responses: '201': description: Create inventory source content: application/json: schema: $ref: '#/components/schemas/InventorySourceResponse' '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: InventorySourceResponse: description: Inventory source response type: object properties: id: description: >- Globally unique surrogate id (BIGINT serialized as string). Use this when acting on rows the caller does not own (e.g. a seller approving an inbound link). type: string sourceId: description: >- Storefront-scoped identifier — unique within the row owner's storefront. Use this for actions on the caller's own rows; use `id` for cross-customer actions. type: string name: description: Display name type: string executionType: description: Execution type type: string enum: - AGENT - MANAGED_SALES_AGENT - LINKED_STOREFRONT - MODULAR_SOURCE connectionType: description: >- Public connection family for a preconfigured ad-server source. Omitted for other inventory-source families. type: string enum: - AD_SERVER adServerProvider: description: >- Ad-server provider for a preconfigured ad-server source. Omitted for other inventory-source families. type: string enum: - citrusad status: description: Source lifecycle status type: string enum: - PENDING - ACTIVE - DISABLED agentId: description: Linked agent ID (when executionType is agent) nullable: true type: string type: description: Agent type nullable: true type: string enum: - SALES - SIGNAL - CREATIVE - OUTCOME endpointUrl: description: Agent endpoint URL nullable: true type: string protocol: description: Agent protocol nullable: true type: string enum: - MCP - A2A description: description: Agent description nullable: true type: string authenticationType: description: Agent authentication type nullable: true type: string enum: - API_KEY - NO_AUTH - JWT - OAUTH - BASIC_AUTH authConfigured: description: Whether the agent has authentication configured type: boolean oauth: description: OAuth authorization info (for OAUTH agents) type: object properties: authorizationUrl: type: string agentId: type: string agentName: type: string required: - authorizationUrl - agentId - agentName additionalProperties: false managedSa: description: >- Embedded-sales-agent state when `executionType` is `MANAGED_SALES_AGENT`. Null/absent for external `AGENT`-type sources. The current REST surface (`/api/v2/storefront/esa/...`) remains the way to mutate this state today; subsequent PRs will move those actions under `/api/v2/storefront/inventory-sources/:sourceId/...`. nullable: true allOf: - $ref: '#/components/schemas/ManagedSalesAgentSummary' linkedStorefront: description: >- Always null. Storefront interchange runs through the ambient wholesale pool: a curator discovers any LISTED storefront’s wholesale inventory automatically, with no per-counterparty link to establish. Retained for response-shape stability. nullable: true allOf: - $ref: '#/components/schemas/LinkedStorefrontSummary' reportingType: description: >- How the underlying agent reports delivery (`WEBHOOK`, `BUCKET`, `POLLING`). Mirrors the AdCP-spec values used when connecting the source. Projected from `storefront_agent_source`; null for non-AGENT sources. nullable: true type: string enum: - WEBHOOK - BUCKET - POLLING reportingPollingCadence: description: >- Polling cadence (`DAILY`, `MONTHLY`) — only meaningful when `reportingType` is `POLLING`. Projected from `storefront_agent_source`; null for non-AGENT sources or non-polling reporting. nullable: true type: string enum: - DAILY - MONTHLY isAdapterSource: description: >- True when this source is routed through an official Scope3-hosted adapter (storefront routing_mode is ADAPTER and the source_id matches the configured adapter). When true, the UI labels this as an official adapter rather than a generic external sales agent. type: boolean agentCapabilityUid: description: >- Explicit reusable SALES Agent capability connected to this Source. Null means the Source requires governed connection reconciliation; endpoint similarity is never used. nullable: true type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ declaredAgentProductMode: description: >- The backing Agent completeness contract. Managed ESA and initial modular Sources project their fixed WHOLESALE contract. nullable: true type: string enum: - WHOLESALE - COMPOSING - BOTH bindingProductMode: description: >- Source product-path selection only when the Agent declares BOTH; null for single-mode Agents. nullable: true type: string enum: - WHOLESALE - COMPOSING - BOTH effectiveProductMode: description: >- Effective mode for new discovery. Null when the explicit Agent connection or declaration is unresolved. nullable: true type: string enum: - WHOLESALE - COMPOSING - BOTH productModeReasons: description: >- Bounded reconciliation reasons when effective mode cannot be resolved. type: array items: type: string enum: - SOURCE_NOT_ACTIVE - AGENT_BINDING_MISSING - AGENT_MODE_UNDECLARED - BOTH_SELECTION_REQUIRED - MERCHANDISING_ACCESS_INACTIVE - WHOLESALE_CATALOG_NOT_READY productPaths: description: >- Readiness for the Agent-supplied and Storefront-built product paths. BOTH exposes both entries; neither path silently replaces the other. type: array items: type: object properties: path: type: string enum: - WHOLESALE - COMPOSING ready: type: boolean reasons: type: array items: type: string enum: - SOURCE_NOT_ACTIVE - AGENT_BINDING_MISSING - AGENT_MODE_UNDECLARED - BOTH_SELECTION_REQUIRED - MERCHANDISING_ACCESS_INACTIVE - WHOLESALE_CATALOG_NOT_READY required: - path - ready - reasons additionalProperties: false createdAt: description: Creation timestamp (ISO 8601) 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))$ updatedAt: description: Last update timestamp (ISO 8601) 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: - id - sourceId - name - executionType - status - agentId - createdAt - updatedAt additionalProperties: false ErrorResponse: description: Standard error response type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false ManagedSalesAgentSummary: description: >- Read-only managed ad-server source state for inventory sources with `executionType=MANAGED_SALES_AGENT`. type: object properties: connectionId: description: >- Surrogate id of the underlying managed ad-server source connection (BIGINT serialized as string). Used internally to route action requests; clients should generally identify the source by the inventory `sourceId` instead. type: string tenantId: description: >- Upstream tenant id for the managed ad-server source. Null until provisioning succeeds. nullable: true type: string adServer: description: Publisher-supplied ad-server config. Null if not yet collected. nullable: true allOf: - $ref: '#/components/schemas/AdServerConfigView' lastError: description: >- Failure reason from the most recent provisioning or test-connection attempt. nullable: true type: string lastErrorCode: description: >- Machine-readable classification of the most recent provisioning failure (`ADAPTER_NETWORK_NOT_FOUND`, `ADAPTER_PERMISSION_DENIED`, `ADAPTER_INVALID_CREDENTIALS`, `ADAPTER_INVALID_CONFIG`, `ADAPTER_CONNECTION_FAILED`, or `INTERNAL_ERROR`). Null when there has been no failure. Same vocabulary as `EsaConnection.lastErrorCode` on the full ad-server connection. nullable: true type: string lastTestedAt: nullable: true 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))$ provisionedAt: nullable: true 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))$ deactivatedAt: nullable: true 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: - connectionId - tenantId - adServer - lastError - lastErrorCode - lastTestedAt - provisionedAt - deactivatedAt additionalProperties: false LinkedStorefrontSummary: description: >- Retired. Never populated — storefront interchange runs through the ambient wholesale pool, so no inline link state is produced. Retained as a reserved, always-null component for response-shape stability. type: object properties: status: description: >- Retired. Storefront interchange no longer uses per-counterparty links; this enum is retained only for response-shape stability and is never emitted. type: string enum: - PENDING - ACTIVE - REJECTED - CANCELLED buyer: description: The storefront that initiated the link (the row owner). allOf: - $ref: '#/components/schemas/StorefrontResponse' seller: description: The storefront whose inventory the link surfaces. allOf: - $ref: '#/components/schemas/StorefrontResponse' requestMessage: nullable: true type: string responseMessage: nullable: true type: string requestedAt: 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))$ respondedAt: nullable: true 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))$ cancelledAt: nullable: true 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))$ cancelledBy: description: Which side stopped the link. Null until status is `CANCELLED`. nullable: true type: string enum: - BUYER - SELLER required: - status - buyer - seller - requestMessage - responseMessage - requestedAt - respondedAt - cancelledAt - cancelledBy additionalProperties: false ApiError: description: Structured error object type: object properties: code: description: Machine-readable error code type: string message: description: Human-readable error message type: string field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false AdServerConfigView: description: >- Non-secret view of the connection ad-server config. Returned by GET endpoints; never contains credentials. oneOf: - type: object properties: type: type: string enum: - google_ad_manager networkCode: description: Google Ad Manager network code. example: '12345678' type: string minLength: 1 maxLength: 32 pattern: ^[0-9]+$ required: - type - networkCode additionalProperties: false - type: object properties: type: type: string enum: - freewheel clientId: nullable: true type: string username: nullable: true type: string environment: type: string enum: - production - staging - sandbox defaultAdvertiserId: nullable: true type: string executionCurrency: default: null nullable: true type: string required: - type - clientId - username - environment - defaultAdvertiserId - executionCurrency additionalProperties: false - type: object properties: type: type: string enum: - springserve email: nullable: true type: string environment: type: string enum: - production defaultDemandPartnerId: nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 rateCurrency: default: null nullable: true type: string required: - type - email - environment - defaultDemandPartnerId - rateCurrency additionalProperties: false - type: object properties: type: type: string enum: - adswizz agencyId: type: integer minimum: -9007199254740991 maximum: 9007199254740991 environment: type: string enum: - AUDIOSERVE baseUrl: type: string forecastingBaseUrl: type: string defaultCurrency: type: string cpmLimit: nullable: true type: number defaultAdvertiserId: nullable: true type: string required: - type - agencyId - environment - baseUrl - forecastingBaseUrl - defaultCurrency - cpmLimit - defaultAdvertiserId additionalProperties: false type: object StorefrontResponse: description: Storefront configuration response type: object properties: storefrontId: description: Surrogate id (BIGINT serialized as string) example: '1234' type: string platformId: description: Public-facing slug example: acme-media type: string name: description: Display name example: Acme Media type: string publisherDomain: description: Publisher domain for the storefront's business profile example: acme.com nullable: true type: string operatorDomain: description: Canonical operator domain example: scope3.com nullable: true type: string brandName: description: Brand name from AAO registry example: Scope3 nullable: true type: string logoUrl: description: Logo URL from brand.json nullable: true 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: description: AAO membership tier. Null when the operator has not set a value. nullable: true type: string enum: - AAO_FOUNDING_MEMBER - AAO_MEMBER - NONE regions: description: >- Legacy merchandising-region context projected from businessProfile. This does not govern brief acceptance or Discovery Card country coverage. type: array items: type: string acceptedCountries: description: >- Operator-confirmed exhaustive country allowlist for brief routing. Null means routing scope has not been confirmed. nullable: true type: array items: type: string pattern: ^[A-Z]{2}$ acceptsAllCountries: description: Whether the operator explicitly accepts briefs from every country. type: boolean advertisingPolicyDisclosure: description: >- Seller-selected Business Rules sections disclosed publicly as Advertising Policies. Empty means no local disclosure. type: array items: description: >- A Business Rules section the seller elects to disclose publicly as Advertising Policies on its Discovery Card. type: string enum: - brief_acceptance - creative_policy advertisedCountries: description: >- Standard primary countries advertised by backing AdCP sales agents. Authoritative for a pure pass-through Discovery Card; inventory evidence otherwise. type: array items: type: string pattern: ^[A-Z]{2}$ advertisedChannels: description: >- Standard primary channels advertised by backing AdCP sales agents. Authoritative for a pure pass-through Discovery Card; inventory evidence otherwise. type: array items: type: string description: description: Operator-curated description (overrides brand.json). nullable: true type: string channels: description: ADCP channel codes the storefront offers. type: array items: type: string website: description: Operator-curated website URL (overrides brand.json). nullable: true type: string discoveryCard: description: >- Canonical buyer-visible storefront identity and coverage. This is distinct from Media Kit merchandising inputs and seller policies. allOf: - $ref: '#/components/schemas/DiscoveryCard' demandContactName: description: Demand contact name. Null when the operator has not set one. nullable: true type: string demandContactEmail: description: Demand contact email. Null when the operator has not set one. nullable: true type: string operatorDomainVerified: description: >- Whether the operator domain has been verified (email match or manual KYC) type: boolean routingMode: description: >- Which backend function the buyer-facing storefront dispatches to: the Merchandising Agent or an expert-run adapter. type: string enum: - CHEF - ADAPTER adapterProviderType: description: >- Expert-run adapter provider when routingMode is `ADAPTER`; null otherwise. nullable: true type: string enum: - amazon - audiostack - elevenlabs - fal - gemini - google - linkedin - meta - openai - pinterest - reddit - snap - spotify - tiktok - veo adapterSourceKind: description: Adapter role when routingMode is `ADAPTER`; null otherwise. nullable: true type: string enum: - sales - creative - signals - measurement - optimization - composite adapterCredentialMode: description: >- Adapter credential mode when routingMode is `ADAPTER`; null otherwise. nullable: true type: string enum: - BYOK plan: description: Storefront plan tier type: string enum: - basic transacting: description: >- Deprecated compatibility projection of `!isPaused`; not proof that the storefront currently satisfies readiness. type: boolean isPaused: 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. type: boolean archivedAt: description: >- When the storefront was archived (read-only thereafter). Null for non-archived storefronts. nullable: true 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: description: >- Deprecated stored-control display status. This is never proof that the storefront can transact; use the readiness projection. type: string enum: - configuring - transacting - archived - neutral - paused 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' 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: >- Declared selling intent from the first onboarding question, or null when the operator has not been asked yet. A record of the operator's answer — what the storefront exposes is always the derived `capabilities`. nullable: true type: string enum: - third_party_connect - sell_through_scope3 compositionPricing: description: >- Composition pricing settings: fallback pricing percentile plus seller pricing facts. Separate from Scope3 contract/billing rate cards. allOf: - $ref: '#/components/schemas/StorefrontCompositionPricingOutput' creativeApproval: description: >- Stored operator setting for creative submissions. It only affects ad-server-backed or product-composition storefronts; pass-through external-agent storefronts ignore this because their sources own review. type: string enum: - auto - manual mediaBuyApproval: description: >- Stored operator setting for new media buys. It only affects ad-server-backed or product-composition storefronts; pass-through external-agent storefronts ignore this because Interchange does not insert an approval queue. type: string enum: - auto - manual capabilitiesLocked: 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. type: boolean advertiseAsAgent: 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. type: boolean sellsThirdPartyInventory: description: >- Operator toggle: when true, the storefront also resells third-party inventory from other Interchange 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: description: Creation timestamp (ISO 8601) 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))$ updatedAt: description: Last update timestamp (ISO 8601) 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))$ businessProfile: description: >- Operator-supplied business profile captured during Murph-led setup. Null when the operator has not shared one. nullable: true allOf: - $ref: '#/components/schemas/BusinessProfileOutput' defaultCurrency: description: >- Seller-confirmed primary settlement currency (ISO-4217). Null until confirmed; required before go-live for Interchange-cleared storefronts. Direct sales adapter storefronts run by our expert agents skip settlement-currency readiness checks because Interchange does not pay the seller on that path. nullable: true type: string paymentCurrencies: description: >- ISO-4217 currencies the storefront 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 - description - channels - website - discoveryCard - demandContactName - demandContactEmail - operatorDomainVerified - routingMode - adapterProviderType - adapterSourceKind - adapterCredentialMode - plan - transacting - isPaused - archivedAt - displayStatus - capabilities - configuredCapabilities - compositionPricing - creativeApproval - mediaBuyApproval - capabilitiesLocked - advertiseAsAgent - createdAt - updatedAt - businessProfile additionalProperties: false DiscoveryCard: description: >- Canonical buyer-visible storefront identity, coverage declaration, and optional Advertising Policies disclosure. Unknown coverage never means worldwide or all channels. 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: description: >- Aggregate channel facets for search and display. Do not combine these with aggregate countries as a cross-product coverage promise. type: array items: type: string countries: 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. type: array items: type: string pattern: ^[A-Z]{2}$ acceptsAllCountries: description: >- True only when the storefront explicitly accepts briefs from every country. type: boolean coverageDeclarations: description: >- Channel and country coverage claims preserved at their source boundaries. A combined filter matches only when one declaration satisfies both dimensions. type: array items: description: >- One source-level coverage claim. Channels and countries are correlated within this declaration; an empty dimension is unknown, not unrestricted. type: object properties: channels: description: Channels accepted by this correlated source declaration. type: array items: type: string countries: description: >- ISO 3166-1 alpha-2 countries accepted by this correlated source declaration. type: array items: type: string pattern: ^[A-Z]{2}$ acceptsAllCountries: description: >- True only when this correlated source declaration explicitly accepts every country. type: boolean required: - channels - countries - acceptsAllCountries additionalProperties: false 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 StorefrontCapabilities: description: >- Which AdCP capabilities the storefront advertises to buyers. Product composition is derived from Source product-path readiness and entitlement. type: object properties: offersCreativeReview: 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. default: false type: boolean offersCampaignApproval: 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. default: false type: boolean offersProductComposition: 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`). default: false type: boolean required: - offersCreativeReview - offersCampaignApproval - offersProductComposition additionalProperties: false StorefrontCompositionPricingOutput: description: >- Storefront composition pricing settings: fallback guidance percentile plus lightly structured seller pricing facts. type: object properties: targetPercentile: default: p75 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. type: string enum: - p50 - p75 - p90 rateCard: description: >- Seller product-pricing facts. Separate from Scope3 contract rate cards. default: facts: [] type: object properties: currency: description: >- Default ISO 4217 currency for pricing facts in this storefront rate card. example: USD type: string minLength: 3 maxLength: 3 facts: default: [] maxItems: 500 type: array items: $ref: '#/components/schemas/StorefrontPricingFactOutput' required: - facts additionalProperties: false required: - targetPercentile - rateCard additionalProperties: false BusinessProfileOutput: description: >- Operator-supplied business profile captured by Murph during storefront setup. 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 (ADCP channel codes — display, olv, ctv, social, audio, dooh). maxItems: 16 type: array items: description: >- Legacy V2 storefront channel code. Values round-trip unchanged; the Discovery Card projection, Marketplace filters, and outbound AdCP capabilities normalize `audio` to canonical `streaming_audio`. type: string enum: - display - olv - ctv - social - audio - dooh regions: description: >- Primary regions the business operates in (ISO 3166-1 alpha-2 country codes or group codes). example: - UK - EMEA 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 Murph 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 Murph-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 StorefrontPricingFactOutput: description: >- Lightly structured seller value-pricing fact. Pricing facts anchor prices and floors; they are not product assembly templates. type: object properties: id: description: >- Stable operator-facing id for this pricing fact. Murph should preserve ids across rewrites when the fact is semantically the same. type: string minLength: 1 maxLength: 120 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ label: description: Short display label for this pricing fact. example: Rich media packages type: string minLength: 1 maxLength: 160 appliesWhen: description: >- Natural-language applicability condition. This is intentionally not a rigid product template; the Merchandising Agent uses it as reasoning context. type: string minLength: 1 maxLength: 2000 hints: description: >- Optional structured hints for deterministic matching. Missing hints are fine. default: {} allOf: - $ref: '#/components/schemas/StorefrontPricingFactHintsOutput' pricing: $ref: '#/components/schemas/StorefrontPricingFactPriceOutput' strength: default: default description: >- `hard_floor` is a must-not-go-below seller constraint. `default` is the preferred value-pricing anchor. `guidance` is advisory context only. type: string enum: - hard_floor - default - guidance 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 Murph. type: string maxLength: 2000 required: - id - label - appliesWhen - hints - pricing - strength additionalProperties: false StorefrontPricingFactHintsOutput: 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. 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 additionalProperties: false StorefrontPricingFactPriceOutput: description: >- Value-pricing anchor extracted from seller rate cards, media kits, or operator instructions. type: object properties: pricingModel: 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. default: cpm type: string enum: - cpm - vcpm - cpc - cpcv - cpv - cpp - cpa - flat_rate - time currency: description: >- ISO 4217 currency for this pricing fact. Falls back to the storefront 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 securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````