> ## 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. # Patch storefront capabilities > Patch one or more storefront capability flags (offersCreativeReview, offersCampaignApproval, offersProductComposition) without sending the rest of the storefront configuration. Rejected with a validation error if the storefront is locked (ad-server-backed inventory sources) and the patch would turn any capability off. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml patch /storefront 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: 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: /storefront: servers: - url: https://api.interchange.io/api/v2 description: Production server patch: tags: - Storefront summary: Patch storefront capabilities description: >- Patch one or more storefront capability flags (offersCreativeReview, offersCampaignApproval, offersProductComposition) without sending the rest of the storefront configuration. Rejected with a validation error if the storefront is locked (ad-server-backed inventory sources) and the patch would turn any capability off. operationId: updateStorefrontCapabilities requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PatchStorefrontCapabilitiesBody' responses: '200': description: Patch storefront capabilities 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: PatchStorefrontCapabilitiesBody: description: >- Request body for patching storefront capability flags (creative review, campaign approval, product composition) and/or recording the declared selling intent. type: object properties: capabilities: description: >- Patch one or more capability flags; omitted flags are left unchanged. Rejected with a VALIDATION error if the storefront is locked (ad-server-backed inventory sources) and the patch would turn any capability off. type: object properties: offersCreativeReview: description: >- Surfaces the creative review protocol surface to buyers. Omit to leave unchanged. type: boolean offersCampaignApproval: description: >- Surfaces the campaign approval protocol surface to buyers. Omit to leave unchanged. type: boolean offersProductComposition: description: >- Storefront composes sellable Products from underlying inventory building blocks. Omit to leave unchanged. type: boolean setupIntent: description: >- Record the operator's declared selling intent. Unless `capabilities` is also passed, applies the matching preset: 'sell_through_scope3' turns product composition on; 'third_party_connect' turns all flags off (clean pass-through). Rejected on storefronts with ad-server-backed sources. type: string enum: - third_party_connect - sell_through_scope3 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: >- Current Business Profile regions projected for storefront-card and qualification consumers, with the legacy regions column used only when no profile regions exist. 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 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: >- Seller-owned pause override. 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: >- Which AdCP capabilities the storefront advertises. Locked on for ad-server-backed storefronts; opt-in for third-party. 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: >- True when the storefront has at least one ad-server-backed inventory source (`executionType=MANAGED_SALES_AGENT`). Locked storefronts reject capability writes that would turn any capability off. type: boolean advertiseAsAgent: description: >- Derived: `capabilitiesLocked || any(capabilities)`. When true, the storefront exposes itself as an AdCP agent and buyers should call the storefront URL. When false, the storefront is not advertised as a public agent; pass-through behavior is handled by the storefront wrapper when a buyer call reaches it. 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 - description - channels - website - demandContactName - demandContactEmail - operatorDomainVerified - routingMode - adapterProviderType - adapterSourceKind - adapterCredentialMode - plan - transacting - isPaused - archivedAt - displayStatus - capabilities - compositionPricing - creativeApproval - mediaBuyApproval - capabilitiesLocked - advertiseAsAgent - createdAt - updatedAt - businessProfile 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 StorefrontCapabilities: description: >- Which AdCP capabilities the storefront advertises to buyers. Ad-server-backed storefronts have all three locked on; third-party storefronts default all off (passthrough). 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: description: >- Storefront composes sellable Products from underlying inventory building blocks instead of passing raw products through. Required for ad-server-backed sources because raw ad-server inventory must be merchandised into buyer-ready products — descriptions, pricing, and packaging happen in the composition layer. 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: >- Operator-supplied voice and merchandising guidance for buyer-facing interactions and reports. This is tone guidance for the Merchandising Agent, not a separate named persona. 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: >- ADCP channel code. `olv` is "online video"; the full set is display, olv, ctv, social, audio, dooh. 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. 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 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 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, such as cpm, vcpm, cpcv, cpv, cpc, cpa, flat_rate, time, or dooh. default: cpm type: string minLength: 1 maxLength: 40 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 ````