> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview Promotion Prices

> Read canonical effective prices for up to 50 products, optionally scoped to an exact marketplace, store and country. Uses the same authoring permissions as the application's preview. Does not publish or change prices.

Requires promotions:write. API keys and delegated Computer credentials resolve organization scope without browser cookies; optional organizationId must match that scope.



## OpenAPI

````yaml /openapi.json post /api/v1/promotions/{promotionId}/preview
openapi: 3.1.0
info:
  title: OmniCommerce API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://omnicommerce.sg/terms
  description: >-
    OmniCommerce API surface for agents and developer integrations. Includes
    public endpoints (merchant discovery, product search, compare, catalog, ACO
    retrieval) and authenticated endpoints (product management via API key
    Bearer tokens).
servers:
  - url: https://omnicommerce.ai
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags:
  - name: agentic-checkout
    description: Merchant-fulfilled agentic checkout
    x-group: Agentic Checkout
  - name: agents
    description: agents
    x-group: Agents
  - name: analytics
    description: Sales performance across marketplaces
    x-group: Analytics
  - name: aops
    description: Agent operating procedures
    x-group: AOPs
  - name: branding
    description: branding
    x-group: Branding
  - name: campaigns
    description: Campaign briefs, offer windows, and marketplace runs
    x-group: Campaigns
  - name: commerce
    description: commerce
    x-group: Commerce
  - name: developer-platform
    description: Authenticated developer platform APIs
    x-group: Developer Platform
  - name: documents
    description: Knowledge base document uploads
    x-group: Knowledge Base
  - name: inventory
    description: Inventory quantities, planning signals, and marketplace listing absence
    x-group: Inventory
  - name: looks
    description: AI-styled product looks
    x-group: Looks
  - name: oauth
    description: OAuth token endpoints
    x-group: OAuth
  - name: orders
    description: Workspace and agentic orders
    x-group: Orders
  - name: organizations
    description: Organization management
    x-group: Organizations
  - name: price-books
    description: Marketplace list-price markup rules
    x-group: Price Books
  - name: products
    description: Product CRUD, bulk import, enrichment, publish, and delist
    x-group: Products
  - name: promotions
    description: Central promotions and marketplace sync
    x-group: Promotions
  - name: public-agent
    description: Public agent discovery and catalog APIs
    x-group: Public Agent
  - name: returns
    description: returns
    x-group: Returns
  - name: reviews
    description: Marketplace product reviews and seller replies
    x-group: Reviews
  - name: scripts
    description: scripts
    x-group: Scripts
  - name: settlements
    description: settlements
    x-group: Settlements
  - name: ucp
    description: Universal Commerce Protocol
    x-group: UCP
paths:
  /api/v1/promotions/{promotionId}/preview:
    post:
      tags:
        - promotions
      summary: Preview Promotion Prices
      description: >-
        Read canonical effective prices for up to 50 products, optionally scoped
        to an exact marketplace, store and country. Uses the same authoring
        permissions as the application's preview. Does not publish or change
        prices.


        Requires promotions:write. API keys and delegated Computer credentials
        resolve organization scope without browser cookies; optional
        organizationId must match that scope.
      operationId: post_v1_promotions_by_promotionid_preview
      parameters:
        - name: promotionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationId:
                  description: >-
                    Required for session auth. Optional for an API key, which
                    already identifies the organization.
                  type: string
                  minLength: 1
                  maxLength: 120
                productIds:
                  minItems: 1
                  maxItems: 50
                  type: array
                  items:
                    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)$
                marketplace:
                  type: string
                  enum:
                    - lazada
                    - shopee
                    - tiktok
                    - shopify
                    - amazon
                    - zalora
                    - ebay
                country:
                  type: string
                  minLength: 1
                  maxLength: 80
                storeId:
                  type: string
                  minLength: 1
                  maxLength: 120
                variantSku:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 120
                    - type: 'null'
              required:
                - productIds
      responses:
        '200':
          description: >-
            Canonical operation result. Inspect aggregate and per-target success
            and marketplace delivery evidence.
          content:
            application/json:
              schema:
                type: object
                properties:
                  previews:
                    type: array
                    items:
                      type: object
                      properties:
                        productId:
                          type: string
                        productName:
                          anyOf:
                            - type: string
                            - type: 'null'
                        basePrice:
                          anyOf:
                            - type: number
                            - type: 'null'
                        currency:
                          anyOf:
                            - type: string
                            - type: 'null'
                        pricing:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties: {}
                      required:
                        - productId
                        - productName
                        - basePrice
                        - currency
                        - pricing
                required:
                  - previews
        '400':
          description: Invalid input or domain validation failed.
        '401':
          description: Missing or expired credentials.
        '403':
          description: >-
            Insufficient current organization, store, operation or OAuth
            permissions.
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Bearer API key for server-to-server access. Session auth is also
        supported in first-party UI flows.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.