> ## 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. # Execute a pinned merchandising simulation variant > Execute one unexpired pinned variant through the resolved merchandising engine and append an immutable Seller Decision Record. The empty request body cannot replace frozen inputs or mutate live Storefront controls. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml post /simulator/scenarios/{scenarioId}/revisions/{revisionId}/variants/{variantId}/executions 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.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 Seller Accounts - name: AI Usage description: Seller Account AI token usage visibility by model - name: MCP description: Model Context Protocol endpoints paths: /simulator/scenarios/{scenarioId}/revisions/{revisionId}/variants/{variantId}/executions: post: tags: - Storefront summary: Execute a pinned merchandising simulation variant description: >- Execute one unexpired pinned variant through the resolved merchandising engine and append an immutable Seller Decision Record. The empty request body cannot replace frozen inputs or mutate live Storefront controls. operationId: executeMerchandisingSimulationVariant parameters: - in: path name: scenarioId schema: 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)$ required: true - in: path name: revisionId schema: 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)$ required: true - in: path name: variantId schema: 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)$ required: true requestBody: required: true content: application/json: schema: type: object properties: {} additionalProperties: false responses: '201': description: Execute a pinned merchandising simulation variant content: application/json: schema: type: object properties: id: 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)$ revisionId: 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)$ variantId: 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)$ intelligenceRunId: type: string attemptNumber: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 status: type: string enum: - succeeded - failed resultCode: nullable: true type: string inputDigest: type: string pattern: ^[a-f0-9]{64}$ overrideDigest: type: string pattern: ^[a-f0-9]{64}$ outputDigest: type: string pattern: ^[a-f0-9]{64}$ decisionRecord: $ref: '#/components/schemas/SellerDecisionRecord' sourceScope: default: mode: storefront sourceId: null sourceName: null diagnostics: includedBundleCount: 0 includedSignalCount: 0 excludedBundleCount: 0 excludedSignalCount: 0 missingLineageCount: 0 ambiguousLineageCount: 0 crossSourceLineageCount: 0 oneOf: - type: object properties: mode: type: string enum: - storefront sourceId: type: string nullable: true enum: - null sourceName: type: string nullable: true enum: - null diagnostics: type: object properties: includedBundleCount: type: integer minimum: 0 maximum: 9007199254740991 includedSignalCount: type: integer minimum: 0 maximum: 9007199254740991 excludedBundleCount: type: integer minimum: 0 maximum: 9007199254740991 excludedSignalCount: type: integer minimum: 0 maximum: 9007199254740991 missingLineageCount: type: integer minimum: 0 maximum: 9007199254740991 ambiguousLineageCount: type: integer minimum: 0 maximum: 9007199254740991 crossSourceLineageCount: type: integer minimum: 0 maximum: 9007199254740991 required: - includedBundleCount - includedSignalCount - excludedBundleCount - excludedSignalCount - missingLineageCount - ambiguousLineageCount - crossSourceLineageCount additionalProperties: false required: - mode - sourceId - sourceName - diagnostics additionalProperties: false - type: object properties: mode: type: string enum: - source sourceId: type: string minLength: 1 maxLength: 500 sourceName: type: string minLength: 1 maxLength: 500 diagnostics: type: object properties: includedBundleCount: type: integer minimum: 0 maximum: 9007199254740991 includedSignalCount: type: integer minimum: 0 maximum: 9007199254740991 excludedBundleCount: type: integer minimum: 0 maximum: 9007199254740991 excludedSignalCount: type: integer minimum: 0 maximum: 9007199254740991 missingLineageCount: type: integer minimum: 0 maximum: 9007199254740991 ambiguousLineageCount: type: integer minimum: 0 maximum: 9007199254740991 crossSourceLineageCount: type: integer minimum: 0 maximum: 9007199254740991 required: - includedBundleCount - includedSignalCount - excludedBundleCount - excludedSignalCount - missingLineageCount - ambiguousLineageCount - crossSourceLineageCount additionalProperties: false required: - mode - sourceId - sourceName - diagnostics additionalProperties: false type: object createdByUserId: nullable: true type: string 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))$ required: - id - revisionId - variantId - intelligenceRunId - attemptNumber - status - resultCode - inputDigest - overrideDigest - outputDigest - decisionRecord - sourceScope - createdByUserId - createdAt additionalProperties: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- The scenario, revision, or variant was not found for this Storefront. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The revision or variant changed before execution evidence could be recorded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: The revision replay window expired and a new revision is required. 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: SellerDecisionRecord: type: object properties: id: type: string status: type: string enum: - pending - responded - declined - failed - booked - delivered - rejected - unattributed - unavailable resolution: type: string enum: - offer - no_match - declined - failure - stalled - unavailable failure: nullable: true type: object properties: type: type: string enum: - llm - system - integration code: nullable: true type: string what: type: string why: type: string sellerAction: type: string enum: - retry - correct_configuration required: - type - code - what - why - sellerAction additionalProperties: false 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))$ purpose: type: object properties: availability: type: string enum: - recorded - unavailable value: nullable: true allOf: - $ref: '#/components/schemas/IntelligenceRunPurpose' required: - availability - value additionalProperties: false buyer: type: object properties: operatorDomain: nullable: true type: string brandDomain: nullable: true type: string country: nullable: true type: string customerId: nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 advertiser: nullable: true description: >- Advertiser BrandRef from the immutable request, falling back only to the run snapshot for legacy records. type: object properties: value: type: string source: type: string enum: - request.brand - request.account.brand - request.account.operator - request.account.account_id - compose_run required: - value - source additionalProperties: false buyingOperator: nullable: true description: >- Buying operator (including an agency or DSP where that is what the operator represents), kept distinct from advertiser and account. type: object properties: value: type: string source: type: string enum: - request.brand - request.account.brand - request.account.operator - request.account.account_id - compose_run required: - value - source additionalProperties: false account: nullable: true description: >- Opaque buyer-declared AdCP account_id when persisted. This is not a CRM id or seller-native account mapping. type: object properties: value: type: string source: type: string enum: - request.brand - request.account.brand - request.account.operator - request.account.account_id - compose_run required: - value - source additionalProperties: false required: - operatorDomain - brandDomain - country - customerId - advertiser - buyingOperator - account additionalProperties: false ask: type: object properties: brief: nullable: true type: string buyingMode: type: string requestAsks: type: array items: type: string inputSnapshotAvailability: type: string enum: - recorded - unavailable required: - brief - buyingMode - requestAsks - inputSnapshotAvailability additionalProperties: false fit: type: object properties: disposition: nullable: true type: string enum: - responded - declined_fit - declined_policy - not_live qualified: nullable: true type: boolean reasonAxis: nullable: true type: string enum: - fit - policy reason: nullable: true type: string policyDecision: nullable: true description: >- Recorded Brief Acceptance result. `needs_human_approval` preserves eligible inventory while requiring an operator decision before a transaction proceeds. Null means the historical run did not record this evidence. allOf: - $ref: '#/components/schemas/StorefrontApprovalPolicyDecision' matchedProducts: type: array items: $ref: '#/components/schemas/IntelligenceRunProductExplanation' unavailableProducts: type: array items: $ref: '#/components/schemas/IntelligenceRunUnpricedProductExplanation' required: - disposition - qualified - reasonAxis - reason - policyDecision - matchedProducts - unavailableProducts additionalProperties: false posture: type: object properties: recommended: nullable: true type: string enum: - direct_fit - hold_value - value_preserving_compromise - tradeoff_ladder - price_first - wholesale_mirror selected: nullable: true type: string enum: - direct_fit - hold_value - value_preserving_compromise - tradeoff_ladder - price_first - wholesale_mirror rationale: nullable: true type: string intensity: nullable: true type: string enum: - low - medium - high signals: type: array items: type: string guidance: type: array items: type: string matchedPricingFactIds: type: array items: type: string operatingInstructionsVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 matchedBuyerInstructionIds: type: array items: type: string override: type: object properties: availability: type: string enum: - recorded - unavailable actor: nullable: true type: string required: - availability - actor additionalProperties: false acceptancePolicyVersion: type: object properties: availability: type: string enum: - recorded - unavailable value: nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - availability - value additionalProperties: false required: - recommended - selected - rationale - intensity - signals - guidance - matchedPricingFactIds - operatingInstructionsVersion - matchedBuyerInstructionIds - override - acceptancePolicyVersion additionalProperties: false response: type: object properties: status: type: string enum: - responded - withheld - failed - unavailable summary: type: string limitations: description: >- Counter-pitch limitations shown with a response. Absence means the historical run did not record them. maxItems: 32 type: array items: type: string minLength: 1 maxLength: 2000 exactSentState: type: object properties: availability: type: string enum: - recorded - unavailable productCount: nullable: true type: integer minimum: 0 maximum: 9007199254740991 proposalHistoryAvailability: type: string enum: - recorded - unavailable required: - availability - productCount - proposalHistoryAvailability additionalProperties: false negotiationChanges: type: object properties: requestAsks: type: array items: type: string refinementApplied: nullable: true required: - requestAsks - refinementApplied additionalProperties: false required: - status - summary - exactSentState - negotiationChanges additionalProperties: false explanation: type: object properties: completeness: type: string enum: - complete - partial truncated: type: boolean reasons: maxItems: 32 type: array items: type: object properties: category: type: string enum: - outside_seller_offering - capability_not_offered - supported_not_configured - no_available_fit - policy_decline - waiting_for_input_or_approval - execution_or_source_failure - evidence_incomplete reasonCode: type: string minLength: 1 maxLength: 128 requirement: type: object properties: text: nullable: true type: string sourceLocator: nullable: true type: string importance: nullable: true type: string enum: - mandatory - preference required: - text - sourceLocator - importance additionalProperties: false description: type: string evidence: type: array items: type: object properties: kind: type: string enum: - request - catalog - policy - execution - configuration - response ref: type: string revision: nullable: true type: string pattern: ^sha256:[a-f0-9]{64}$ sourceLocator: nullable: true type: string observedAt: 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: - kind - ref - revision - sourceLocator - observedAt additionalProperties: false accountableBoundary: nullable: true type: string responsible: nullable: true type: string nextAction: oneOf: - type: object properties: kind: type: string enum: - none unavailableReason: type: string required: - kind - unavailableReason additionalProperties: false - type: object properties: kind: type: string enum: - open_source_diagnostics sourceId: type: string minLength: 1 sourceName: nullable: true type: string label: type: string required: - kind - sourceId - sourceName - label additionalProperties: false type: object required: - category - reasonCode - requirement - description - evidence - accountableBoundary - responsible - nextAction additionalProperties: false required: - completeness - truncated - reasons additionalProperties: false approval: type: object properties: availability: type: string enum: - recorded - unavailable id: nullable: true type: string status: nullable: true type: string enum: - pending - approved - rejected - revoked reviewedBy: nullable: true type: string reviewedAt: 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))$ reviewerNotes: nullable: true type: string forwardedAt: 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: - availability - id - status - reviewedBy - reviewedAt - reviewerNotes - forwardedAt additionalProperties: false outcome: type: object properties: state: type: string enum: - pending - booked - delivered - rejected - failed - unattributed - unavailable eventType: nullable: true type: string eventAt: 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))$ mediaBuyId: nullable: true type: string mediaBuyStatus: nullable: true type: string pendingApprovalId: nullable: true type: string bookedBudget: nullable: true type: number deliveredImpressions: nullable: true type: number deliveredSpend: nullable: true type: number deliveredCurrency: nullable: true type: string attribution: type: object properties: availability: type: string enum: - recorded - unavailable model: nullable: true type: string matchedRunId: nullable: true type: string matchedProductIds: type: array items: type: string required: - availability - model - matchedRunId - matchedProductIds additionalProperties: false required: - state - eventType - eventAt - mediaBuyId - mediaBuyStatus - pendingApprovalId - bookedBudget - deliveredImpressions - deliveredSpend - deliveredCurrency - attribution additionalProperties: false learning: type: object properties: analyticsEligibility: type: object properties: status: type: string enum: - eligible - ineligible - unavailable reason: type: string required: - status - reason additionalProperties: false postureContribution: type: object properties: availability: type: string enum: - recorded - unavailable selected: nullable: true type: string enum: - direct_fit - hold_value - value_preserving_compromise - tradeoff_ladder - price_first - wholesale_mirror recommended: nullable: true type: string enum: - direct_fit - hold_value - value_preserving_compromise - tradeoff_ladder - price_first - wholesale_mirror required: - availability - selected - recommended additionalProperties: false recommendationLineage: type: object properties: availability: type: string enum: - recorded - unavailable required: - availability additionalProperties: false required: - analyticsEligibility - postureContribution - recommendationLineage additionalProperties: false provenance: type: object properties: modelProvider: nullable: true type: string modelName: type: string operatingInstructionsVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 durationMs: nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - modelProvider - modelName - operatingInstructionsVersion - durationMs additionalProperties: false required: - id - status - resolution - failure - createdAt - purpose - buyer - ask - fit - posture - response - explanation - approval - outcome - learning - provenance additionalProperties: false description: >- Canonical seller-readable decision record projected from one storefront intelligence run and its attributed approval/commercial evidence. 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 IntelligenceRunPurpose: type: string enum: - live - setup_test - simulation - probe - evaluation description: >- Trusted execution classification. Null is reserved for historical runs recorded before purpose was required. StorefrontApprovalPolicyDecision: type: string enum: - definitely_on_policy - definitely_not_on_policy - needs_human_approval description: >- Policy confidence for storefront approval automation. `definitely_on_policy` is eligible for automatic approval, `definitely_not_on_policy` is a clear policy conflict, and `needs_human_approval` is the safe default for ambiguous or incomplete evidence. IntelligenceRunProductExplanation: type: object properties: productId: nullable: true type: string name: nullable: true type: string description: nullable: true type: string reasoning: nullable: true type: string pricing: nullable: true allOf: - $ref: '#/components/schemas/IntelligenceRunProductPricingExplanation' bundleIds: type: array items: type: string signalIds: type: array items: type: string formatIds: type: array items: $ref: '#/components/schemas/IntelligenceRunProductFormatExplanation' required: - productId - name - description - reasoning - pricing - bundleIds - signalIds - formatIds additionalProperties: false description: >- Buyer-safe explanation of one product selected for the storefront response. IntelligenceRunUnpricedProductExplanation: type: object properties: name: nullable: true type: string reasoning: nullable: true type: string reason: type: string bundleIds: type: array items: type: string signalIds: type: array items: type: string required: - name - reasoning - reason - bundleIds - signalIds additionalProperties: false description: >- Composition the model considered but the platform omitted because it could not be priced authoritatively. 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 IntelligenceRunProductPricingExplanation: type: object properties: baseCpm: nullable: true type: number currency: nullable: true type: string operatorDiscount: nullable: true type: number finalCpm: nullable: true type: number required: - baseCpm - currency - operatorDiscount - finalCpm additionalProperties: false description: Server-computed CPM pricing summary for a selected composition. IntelligenceRunProductFormatExplanation: type: object properties: agentUrl: nullable: true type: string id: nullable: true type: string required: - agentUrl - id additionalProperties: false description: Creative format selected for an explained product. securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````