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

# Retrieve product variants

> Retrieves the variants of an existing marketplace product. Product slug is supported in place of product ID in the path. Commerce Engine returns the corresponding product variants information.



## OpenAPI

````yaml get /catalog/marketplace/products/{product_id}/variants
openapi: 3.1.0
info:
  version: '1.0'
  title: CE Storefront APIs
  summary: Customer-facing e-commerce API for building exceptional shopping experiences
  description: >-
    Public-facing API for Commerce Engine storefronts, enabling seamless
    shopping experiences with product browsing, cart management, checkout
    processing, user accounts, and order tracking. Perfect for building web,
    mobile, and headless commerce applications.
  contact:
    name: Support
    email: support@commercengine.io
    url: https://www.commercengine.io/contact-us
  license:
    url: https://www.commercengine.io/contact-us
    name: All Rights Reserved
servers:
  - url: https://staging.api.commercengine.io/api/v1/{store_id}/storefront
    description: Staging Server
    variables:
      store_id:
        description: Store ID
        default: store_id
    x-speakeasy-server-id: staging
  - url: https://prod.api.commercengine.io/api/v1/{store_id}/storefront
    description: Prod Server
    variables:
      store_id:
        description: Store ID
        default: store_id
    x-speakeasy-server-id: prod
security: []
tags:
  - name: Analytics
    description: Analytics
  - name: Auth
    description: auth
  - name: Campaigns
    description: Campaigns
  - name: Carts
    description: Carts
  - name: Catalog
    description: Catalog
  - name: Common
    description: Common
  - name: Coupons & promotions
    description: Coupons & promotions
  - name: Customers
    description: Customers
  - name: Juspay
    description: Juspay Payments
  - name: KYC
    description: KYC
  - name: Marketplace
    description: Marketplace
  - name: Orders
    description: Orders
  - name: Others
    description: Others
  - name: Payments
    description: Payments
  - name: PayU
    description: PayU Payments
  - name: POS
    description: POS
  - name: Shipping
    description: Shipping
  - name: Store
    description: Store
  - name: Subscriptions
    description: Subscriptions
externalDocs:
  url: https://llm-docs.commercengine.io
  description: Commerce Engine API Reference Documentation
paths:
  /catalog/marketplace/products/{product_id}/variants:
    get:
      tags:
        - Marketplace
      summary: Retrieve product variants
      description: >-
        Retrieves the variants of an existing marketplace product. Product slug
        is supported in place of product ID in the path. Commerce Engine returns
        the corresponding product variants information.
      operationId: list-marketplace-product-variants
      parameters:
        - $ref: '#/components/parameters/CustomerGroupId'
        - name: inventory
          in: query
          description: >-
            Determines whether to include or exlude inventory details in
            response json
          schema:
            type: boolean
        - name: product_id
          in: path
          description: Product ID or product slug. Either is accepted in the path.
          required: true
          schema:
            type: string
            examples:
              - 01H7YK0C86V9PGT0HXRJVEZXJQ
              - detox-candy
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - success
                  - content
                properties:
                  message:
                    type: string
                    examples:
                      - Products retrieved successfully.
                  success:
                    type: boolean
                  content:
                    properties:
                      variants:
                        type: array
                        items:
                          $ref: '#/components/schemas/Variant'
                    required:
                      - variants
                    type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - Authorization: []
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/operations/list-marketplace-product-variants
        description: API reference for the list-marketplace-product-variants operation
components:
  parameters:
    CustomerGroupId:
      name: x-customer-group-id
      in: header
      required: false
      schema:
        type: string
      description: >-
        This param is used to determine product pricing, promotions, and
        subscription rates.  If a valid customer group id is provided, pricing
        details will be retrieved accordingly.  If no matching data is found for
        the specified customer group id, the system will fall back to the
        default customer group id.  If no data is found for the default group
        either, the highest applicable price will be returned.
  schemas:
    Variant:
      title: ProductVariant
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Variant
        description: API reference for the Variant schema
      required:
        - id
        - product_id
        - sku
        - slug
        - name
        - product_name
        - short_description
        - active
        - stock_available
        - on_promotion
        - on_subscription
        - is_default
        - associated_options
        - images
        - videos
        - pricing
        - subscription
        - promotion
      properties:
        id:
          description: variant id
          type: string
        product_id:
          description: product id
          type: string
        sku:
          description: variant sku
          type:
            - string
            - 'null'
        slug:
          type: string
        name:
          description: variant name
          type: string
        product_name:
          description: variant name
          type: string
        short_description:
          type:
            - string
            - 'null'
        active:
          type: boolean
          readOnly: true
        stock_available:
          type: boolean
          readOnly: true
        backorder:
          description: >-
            Indicates whether the item is being fulfilled as a backorder. When
            true, the item is not currently in stock and will ship later once
            inventory is available. This may result in the order being split
            into multiple shipments, with delays for the backordered portion.
          type: boolean
        on_promotion:
          type: boolean
          readOnly: true
        on_subscription:
          type: boolean
          readOnly: true
        is_default:
          description: >-
            Indicates whether a variant is marked as the default variant for a
            product
          type: boolean
          readOnly: true
        associated_options:
          $ref: '#/components/schemas/AssociatedOption'
          description: >-
            This object contains multiple dynamic keys. Each key is a string
            derived from the attribute key, and the value is an object of the
            type `AssociatedOption`.
        images:
          type: array
          items:
            $ref: '#/components/schemas/ProductImage'
        videos:
          type: array
          items:
            $ref: '#/components/schemas/ProductVideo'
        pricing:
          $ref: '#/components/schemas/ProductPricing'
        subscription:
          type: array
          items:
            $ref: '#/components/schemas/ProductSubscription'
        promotion:
          $ref: '#/components/schemas/ProductPromotion'
        inventory:
          type: array
          items:
            $ref: '#/components/schemas/LotBatchDetail'
      examples: []
    AssociatedOption:
      title: AssociatedOption
      description: >-
        An object where each key is an option name, and the value describes the
        option details.
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/AssociatedOption
        description: API reference for the AssociatedOption schema
      additionalProperties:
        oneOf:
          - $ref: '#/components/schemas/ColorOption'
          - $ref: '#/components/schemas/SingleSelectOption'
      examples:
        - background_color:
            name: Background Color
            value:
              name: Blue
              hexcode: '#0000FF'
            type: color
          size:
            name: Size
            value: Large
            type: single-select
    ProductImage:
      title: ProductImage
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/ProductImage
        description: API reference for the ProductImage schema
      required:
        - id
        - title
        - alternate_text
        - sort_order
        - url_tiny
        - url_thumbnail
        - url_standard
        - url_zoom
      properties:
        id:
          type: string
        title:
          type:
            - string
            - 'null'
        alternate_text:
          type:
            - string
            - 'null'
        sort_order:
          type: integer
        url_tiny:
          type: string
        url_thumbnail:
          type: string
        url_standard:
          type: string
        url_zoom:
          type: string
      examples: []
    ProductVideo:
      title: ProductVideo
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/ProductVideo
        description: API reference for the ProductVideo schema
      required:
        - title
        - alternate_text
        - sort_order
        - video_preview_url
        - video_stream_hls_url
        - video_stream_dash_url
        - image_thumbnail_url
        - video_duration
      properties:
        title:
          type:
            - string
            - 'null'
        alternate_text:
          type:
            - string
            - 'null'
        sort_order:
          type: integer
        video_preview_url:
          type: string
        video_stream_hls_url:
          type: string
        video_stream_dash_url:
          type: string
        image_thumbnail_url:
          type: string
        video_duration:
          description: in seconds
          type: integer
      examples: []
    ProductPricing:
      title: ProductPricing
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/ProductPricing
        description: API reference for the ProductPricing schema
      required:
        - currency
        - tax_type
        - tax_rate
        - price_including_tax
        - listing_price
        - selling_price
        - min_order_quantity
        - max_order_quantity
        - incremental_quantity
        - selling_price_excluding_tax
      properties:
        currency:
          type: string
        tax_type:
          type: string
          default: GST
          const: GST
          examples:
            - GST
        tax_rate:
          type: number
          format: double
        price_including_tax:
          type: boolean
          format: double
          examples:
            - false
        listing_price:
          type: number
          format: double
        selling_price:
          type: number
          format: double
        min_order_quantity:
          type: integer
          default: 1
        max_order_quantity:
          type:
            - integer
            - 'null'
        incremental_quantity:
          type: integer
          default: 1
        selling_price_excluding_tax:
          type: number
          format: double
      examples: []
    ProductSubscription:
      title: ProductSubscription
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/ProductSubscription
        description: API reference for the ProductSubscription schema
      required:
        - id
        - subscription_plan
        - subscription_price
        - billing_interval
        - billing_frequency
        - billing_limit
        - fulfill_separately
        - order_interval
        - order_frequency
        - order_limit
        - minimum_quantity
        - billing_trial_days
      properties:
        id:
          type: string
        subscription_plan:
          type: string
        subscription_price:
          type: number
          format: double
        billing_interval:
          description: >-
            Billing interval determines the frequency for which the customer is
            charged for the subscription itself.
          type: integer
        billing_frequency:
          type: string
          enum:
            - weekly
            - monthly
            - annually
          examples:
            - monthly
        billing_limit:
          description: >-
            Optionally limit the number of times this subscription will invoice
            the customer.
          type: integer
        fulfill_separately:
          type: boolean
          default: false
        order_interval:
          description: >-
            order interval defines the frequency of when the subscription sends
            customers the product
          type: integer
        order_frequency:
          type: string
          enum:
            - weekly
            - monthly
            - annully
          examples:
            - monthly
        order_limit:
          description: >-
            By default this is set to unlimited, meaning the subscription will
            fulfill indefinitely. Changing the Limit to 10 would force the
            subscription to end after the tenth interval had been fulfilled.
          type: integer
        minimum_quantity:
          description: The quantity of the plan to which the customer should be subscribed
          type: integer
        billing_trial_days:
          description: Use in digital product only for trial period
          type: integer
      examples: []
    ProductPromotion:
      title: ProductPromotion
      description: >-
        Active promotion on a product. `null` when `on_promotion` is `false`.
        The `details` field uses `promotion_type` as discriminator to determine
        the promotion structure.
      type:
        - object
        - 'null'
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/ProductPromotion
        description: API reference for the ProductPromotion schema
      required:
        - id
        - starts_at
        - expires_at
        - details
      properties:
        id:
          type: string
        starts_at:
          type: string
          format: date-time
        expires_at:
          description: When the promotion ends. `null` for promotions with no expiry.
          type:
            - string
            - 'null'
          format: date-time
        details:
          description: >-
            Promotion rules and pricing. Use `promotion_type` to determine the
            structure: `discount` (percentage/flat off), `fixed-price` (override
            price), `volume-based` (buy X at Y price), or `free-goods` (buy X
            get Y free).
          discriminator:
            propertyName: promotion_type
            mapping:
              discount:
                $ref: '#/components/schemas/DiscountBasedPromotion'
              fixed-price:
                $ref: '#/components/schemas/FixedPricePromotion'
              volume-based:
                $ref: '#/components/schemas/VolumeBasedPromotion'
              free-goods:
                $ref: '#/components/schemas/FreeGoodsPromotion'
          oneOf:
            - $ref: '#/components/schemas/DiscountBasedPromotion'
            - $ref: '#/components/schemas/FixedPricePromotion'
            - $ref: '#/components/schemas/VolumeBasedPromotion'
            - $ref: '#/components/schemas/FreeGoodsPromotion'
    LotBatchDetail:
      title: LotBatchDetail
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/LotBatchDetail
        description: API reference for the LotBatchDetail schema
      required:
        - lot_batch
        - mfg_date
        - exp_date
        - manufacturer
        - stock_quantity
      properties:
        lot_batch:
          type: string
        mfg_date:
          type:
            - string
            - 'null'
          format: date
        exp_date:
          type:
            - string
            - 'null'
          format: date
        manufacturer:
          type:
            - string
            - 'null'
        stock_quantity:
          type: integer
    ColorOption:
      title: ColorOption
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/ColorOption
        description: API reference for the ColorOption schema
      required:
        - name
        - type
        - value
      properties:
        name:
          description: The name of the associated option.
          type: string
        type:
          description: The type of the associated option.
          const: color
        value:
          type: object
          properties:
            hexcode:
              description: 'The hex code of the color (e.g., #000000).'
              type: string
              format: color-hex
              pattern: ^#(?:[0-9a-fA-F]{3}){1,2}$
            name:
              type: string
              description: The name of the color.
          required:
            - name
            - hexcode
    SingleSelectOption:
      title: SingleSelectOption
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/SingleSelectOption
        description: API reference for the SingleSelectOption schema
      required:
        - name
        - type
        - value
      properties:
        name:
          description: The name of the associated option.
          type: string
        type:
          description: The type of the associated option.
          const: single-select
        value:
          description: The value of the associated option
          type: string
    DiscountBasedPromotion:
      title: DiscountBasedPromotion
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/DiscountBasedPromotion
        description: API reference for the DiscountBasedPromotion schema
      required:
        - promotion_type
        - discount_type
      properties:
        promotion_type:
          type: string
          enum:
            - discount
            - volume-based
            - fixed-price
            - free-goods
          const: discount
        discount_type:
          type: string
          enum:
            - percentage
            - fixed-amount
        discount_percent:
          description: '''> 0'' if discount_type = percentage, otherwise set 0.'
          type: number
        discount_fixed_amount:
          description: '''> 0'' if discount_type = fixed-amount, otherwise set 0.'
          type: integer
    FixedPricePromotion:
      title: FixedPricePromotion
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/FixedPricePromotion
        description: API reference for the FixedPricePromotion schema
      required:
        - promotion_type
        - offer_price
      properties:
        promotion_type:
          type: string
          enum:
            - discount
            - volume-based
            - fixed-price
            - free-goods
          const: fixed-price
          readOnly: true
        offer_price:
          type: number
    VolumeBasedPromotion:
      title: VolumeBasedPromotion
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/VolumeBasedPromotion
        description: API reference for the VolumeBasedPromotion schema
      required:
        - promotion_type
        - slabs
      properties:
        promotion_type:
          type: string
          enum:
            - discount
            - volume-based
            - fixed-price
            - free-goods
          const: volume-based
          readOnly: true
        slabs:
          type: array
          items:
            type: object
            properties:
              quantity_limit:
                description: The minimum quantity required to qualify for the discount.
                type: integer
              discount_percent:
                description: >-
                  The percentage discount applied when the quantity limit is
                  reached.
                type: number
                readOnly: true
            required:
              - quantity_limit
              - discount_percent
    FreeGoodsPromotion:
      title: FreeGoodsPromotion
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/FreeGoodsPromotion
        description: API reference for the FreeGoodsPromotion schema
      required:
        - promotion_type
        - buy_quantity
        - get_quantity
      properties:
        promotion_type:
          type: string
          enum:
            - discount
            - volume-based
            - fixed-price
            - free-goods
          const: free-goods
          readOnly: true
        buy_quantity:
          description: The quantity of items a customer must buy to receive free goods.
          type: integer
        get_quantity:
          description: The quantity of free goods the customer receives.
          type: integer
  responses:
    Unauthorized:
      description: Not authorized for given operation on the Resource
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
              - code
            properties:
              message:
                type: string
                examples:
                  - Not authorized for given operation on the Resource.
                x-speakeasy-error-message: true
              success:
                type: boolean
                default: false
              code:
                type: string
                examples:
                  - unauthorized
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
              - code
            properties:
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              code:
                type: string
  securitySchemes:
    Authorization:
      type: http
      description: Access token
      scheme: bearer

````