> ## 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.

# Assign Products to Promotion

> Assign one or more products to a promotion. Creates pending marketplace sync rows; call sync after assign. Requires `promotions:write`.



## OpenAPI

````yaml /openapi.json post /api/v1/promotions/{promotionId}/products
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.sg
    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: campaigns
    description: Campaign briefs, offer windows, and marketplace runs
    x-group: Campaigns
  - name: developer-platform
    description: Authenticated developer platform APIs
    x-group: Developer Platform
  - name: documents
    description: Knowledge base document uploads
    x-group: Knowledge Base
  - 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: settlements
    description: settlements
    x-group: Settlements
  - name: ucp
    description: Universal Commerce Protocol
    x-group: UCP
paths:
  /api/v1/promotions/{promotionId}/products:
    post:
      tags:
        - promotions
      summary: Assign Products to Promotion
      description: >-
        Assign one or more products to a promotion. Creates pending marketplace
        sync rows; call sync after assign. Requires `promotions:write`.
      operationId: post_v1_promotions_by_promotionid_products
      parameters:
        - name: promotionId
          in: path
          required: true
          schema:
            type: string
        - name: organizationId
          in: query
          required: false
          description: >-
            Optional organization scope for session-authenticated calls. OAuth
            client credentials resolve the organization from the token.
          schema:
            type: string
            maxLength: 120
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - productIds
              properties:
                organizationId:
                  type: string
                  maxLength: 120
                productIds:
                  type: array
                  minItems: 1
                  maxItems: 200
                  items:
                    type: string
                    format: uuid
                variantSku:
                  type:
                    - string
                    - 'null'
                  maxLength: 120
                priority:
                  type: integer
                  minimum: 0
                  maximum: 1000
                  default: 0
                productDiscounts:
                  type: array
                  maxItems: 200
                  description: >-
                    Optional per-product discount for product discounts and
                    flash sales. Uses the campaign discount type. Null restores
                    the shared discount. Shopee and TikTok publish the resulting
                    price. Lazada vouchers and Shopify fail sync while any
                    product has its own discount.
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - productId
                      - discountValue
                    properties:
                      productId:
                        type: string
                        format: uuid
                      discountValue:
                        type:
                          - number
                          - 'null'
                        exclusiveMinimum: 0
            example:
              productIds:
                - f831911c-ba05-4c83-9a03-e026e0aaf102
              priority: 0
      responses:
        '201':
          description: Products assigned.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden or missing `promotions:write` scope
        '500':
          description: Internal Server Error
      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.