> ## 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 product. Returns the corresponding variant list. Product slug is supported in place of product ID in the path.



## OpenAPI

````yaml https://openapi.commercengine.io/ce-storefront.json get /catalog/products/{product_id}/variants
openapi: 3.2.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: section-identity
    summary: Identity
    kind: nav
  - name: Authentication
    description: >-
      Start an anonymous session for each visitor, then sign them in or register
      them with a one-time password over SMS, WhatsApp or email, or with a
      password. Every flow ends in the access and refresh tokens your app sends
      with each request.
    summary: Authentication
    kind: nav
    parent: section-identity
  - name: Account recovery
    description: >-
      Get a shopper back into their account: reset a forgotten password, or find
      the account by its KYC document numbers and sign in with the one-time code
      sent to it.
    summary: Account recovery
    kind: nav
    parent: section-identity
  - name: Users
    description: >-
      The signed-in shopper's `User`: read and update the profile, manage the
      profile image, change the password, check whether the email and phone are
      verified, and deactivate or delete the account.
    summary: Users
    kind: nav
    parent: section-identity
  - name: Customer attributes
    description: >-
      The store's customer attributes (`StorefrontAttribute`) and the shopper's
      values for them (`UserAttributeValue`), for building profile forms.
    summary: Customer attributes
    kind: nav
    parent: section-identity
  - name: section-customers
    summary: Customers
    kind: nav
  - name: Addresses
    description: >-
      The customer's saved addresses, as `CustomerAddress` objects, to offer at
      checkout and manage on the account page.
    summary: Addresses
    kind: nav
    parent: section-customers
  - name: Bank accounts
    description: >-
      The customer's bank accounts, as `CustomerBankAccount` objects: add,
      update, verify and remove them.
    summary: Bank accounts
    kind: nav
    parent: section-customers
  - name: KYC documents
    description: >-
      The KYC documents the store requires (`KycDocumentConfig`) and the ones
      the customer has added (`Document`). Verify a document number before
      saving it.
    summary: KYC documents
    kind: nav
    parent: section-customers
  - name: Saved payment methods
    description: >-
      The cards, UPI IDs and wallets the customer has saved, to offer at
      checkout.
    summary: Saved payment methods
    kind: nav
    parent: section-customers
  - name: Mandates
    description: >-
      Recurring-payment mandates the customer authorizes (`CustomerMandate`):
      create, update, pause, resume or revoke them, and list the debits
      scheduled against them (`MandateDebitSchedule`).
    summary: Mandates
    kind: nav
    parent: section-customers
  - name: Loyalty
    description: >-
      The store's `LoyaltyProgram` and the customer's standing in it: their
      `CustomerLoyalty` and `LoyaltyPointActivity`. Redeem points on a cart
      under Carts.
    summary: Loyalty
    kind: nav
    parent: section-customers
  - name: Credit
    description: >-
      What the customer can spend on credit: their bank-transfer
      `CustomerCreditBalance` and their credit line
      (`CustomerCreditLineBalance`). Apply the credit balance to a cart under
      Carts.
    summary: Credit
    kind: nav
    parent: section-customers
  - name: section-catalog
    summary: Catalog
    kind: nav
  - name: Products
    description: >-
      Browse and search the store's catalog: list `Product`s and SKUs, read a
      product and its variants, and show similar, up-sell and cross-sell items.
    summary: Products
    kind: nav
    parent: section-catalog
  - name: Categories
    description: >-
      The store's categories, as `ProductCategory` objects with their child
      categories, for navigation and filtering.
    summary: Categories
    kind: nav
    parent: section-catalog
  - name: Reviews
    description: >-
      Reviews of products and sellers: show them, let a shopper review a
      product, and list what the customer has reviewed or can review next.
    summary: Reviews
    kind: nav
    parent: section-catalog
  - name: Marketplace catalog
    description: >-
      A marketplace's catalog as shoppers browse it: `MarketplaceProduct`s with
      their seller, variants, SKUs, categories and reviews, plus search and
      recommendations.
    summary: Marketplace catalog
    kind: nav
    parent: section-catalog
  - name: section-shopping
    summary: Shopping
    kind: nav
  - name: Carts
    description: >-
      The shopper's `Cart`: create it, add, update or remove items, set the
      address, and apply loyalty points or credit balance. Each update returns
      the full, updated `Cart`.
    summary: Carts
    kind: nav
    parent: section-shopping
  - name: Coupons & promotions
    description: >-
      The coupons and promotions a shopper can use: list what the store offers,
      see which apply to a cart and why the rest don't, and apply or remove a
      coupon.
    summary: Coupons & promotions
    kind: nav
    parent: section-shopping
  - name: Fulfillment
    description: >-
      How an order reaches the shopper: check that a pincode is serviceable,
      list the delivery and collect-in-store options for a cart, and save the
      cart's choice.
    summary: Fulfillment
    kind: nav
    parent: section-shopping
  - name: Wishlist
    description: Products the shopper saved for later, as `Item` objects.
    summary: Wishlist
    kind: nav
    parent: section-shopping
  - name: section-orders
    summary: Orders
    kind: nav
  - name: Orders
    description: >-
      Place an order from the cart and follow it afterwards: list orders, read
      an `OrderDetail`, cancel it, list its shipments, and offer past items
      again.
    summary: Orders
    kind: nav
    parent: section-orders
  - name: Order payments
    description: >-
      Pay for an order after checkout: poll its payment status, retry or cancel
      a payment request, and list its `OrderPayment`s and refunds.
    summary: Order payments
    kind: nav
    parent: section-orders
  - name: Returns
    description: >-
      Return delivered items: create an `OrderReturn`, add attachments, follow
      it, and cancel it.
    summary: Returns
    kind: nav
    parent: section-orders
  - name: section-payments
    summary: Payments
    kind: nav
  - name: Payments
    description: >-
      The payment methods the store accepts and the checks around paying with
      them: card BIN details, VPA and IFSC lookups, and authenticating a payment
      with a direct OTP.
    summary: Payments
    kind: nav
    parent: section-payments
  - name: PayU
    description: >-
      Generate the hash PayU requires on the requests your app sends it, such as
      validating a UPI ID or saving and retrieving cards.
    summary: PayU
    kind: nav
    parent: section-payments
  - name: section-store
    summary: Store
    kind: nav
  - name: Store
    description: >-
      The store your app runs on: check that it exists and read its
      `StoreConfig`, from brand and currency to KYC, customer groups and payment
      providers.
    summary: Store
    kind: nav
    parent: section-store
  - name: Sellers
    description: >-
      A marketplace's sellers: a seller's profile (`SellerDetail`) and the
      sellers authorized for a customer (`SellerInfo`).
    summary: Sellers
    kind: nav
    parent: section-store
  - name: Locations
    description: Countries, states and pincodes for address forms.
    summary: Locations
    kind: nav
    parent: section-store
  - name: Newsletter
    description: Sign a shopper up for the store's newsletter.
    summary: Newsletter
    kind: nav
    parent: section-store
externalDocs:
  url: https://llm-docs.commercengine.io
  description: Commerce Engine API Reference Documentation
paths:
  /catalog/products/{product_id}/variants:
    get:
      tags:
        - Products
      summary: Retrieve product variants
      description: >-
        Retrieves the variants of an existing product. Returns the corresponding
        variant list. Product slug is supported in place of product ID in the
        path.
      operationId: list-product-variants
      parameters:
        - $ref: '#/components/parameters/CustomerGroupId'
        - name: inventory
          in: query
          description: >-
            Determines whether to include or exclude 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
            minLength: 1
      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
          links:
            AddVariantToCart:
              operationId: update-cart
              requestBody:
                product_id: $request.path.product_id
                variant_id: $response.body#/content/variants/0/id
              description: >-
                Add a variant to a cart. Use the parent `product_id` and a
                variant's `id` as `variant_id`.
        '400':
          $ref: '#/components/responses/BadRequest'
          description: The request parameters or customer group are invalid.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - Authorization: []
        - X-Api-Key: []
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/operations/list-product-variants
        description: API reference for the list-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
            - 'null'
        product_name:
          description: variant name
          type: string
        short_description:
          type:
            - string
            - 'null'
        active:
          type: boolean
          readOnly: true
        stock_available:
          type: boolean
          readOnly: true
        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:
          description: >-
            Variant pricing for the applicable customer group. `null` when no
            pricing is configured for the variant.
          oneOf:
            - $ref: '#/components/schemas/ProductPricing'
            - type: 'null'
        subscription:
          type: array
          items:
            $ref: '#/components/schemas/ProductSubscription'
        promotion:
          $ref: '#/components/schemas/ProductPromotion'
        shipping:
          $ref: '#/components/schemas/ProductShipping'
          description: >-
            Variant-level shipping configuration. Emitted by the standalone
            variant list/detail endpoints; `null` when no variant shipping is
            configured. Omitted from variants embedded in a product-listing
            payload.
        packaging:
          $ref: '#/components/schemas/Packaging'
          description: >-
            Variant-level packing dimensions. Emitted by the standalone variant
            list/detail endpoints; `null` when none configured. Omitted from
            variants embedded in a product-listing payload.
        metadata:
          description: >-
            Freeform metadata key/value map. Emitted when the variant is
            returned inside a product-listing payload.
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
        on_offer:
          description: Indicates whether the variant currently has an active offer.
          type: boolean
        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:
        - id
        - title
        - alternate_text
        - sort_order
        - video_preview_url
        - video_stream_hls_url
        - video_stream_dash_url
        - image_thumbnail_url
        - video_duration
      properties:
        id:
          type: string
        title:
          type:
            - string
            - 'null'
        alternate_text:
          type:
            - string
            - 'null'
        sort_order:
          type: integer
        video_preview_url:
          type:
            - string
            - 'null'
        video_stream_hls_url:
          type:
            - string
            - 'null'
        video_stream_dash_url:
          type:
            - string
            - 'null'
        image_thumbnail_url:
          type:
            - string
            - 'null'
        video_duration:
          description: in seconds
          type:
            - integer
            - 'null'
      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
          enum:
            - GST
            - VAT
            - ECO
          examples:
            - GST
        tax_rate:
          type: number
          format: double
        price_including_tax:
          type: boolean
          examples:
            - false
        listing_price:
          type: number
          format: double
        selling_price:
          type: number
          format: double
        min_order_quantity:
          description: '`null` means no quantity constraint.'
          type:
            - integer
            - 'null'
          default: 1
        max_order_quantity:
          type:
            - integer
            - 'null'
        incremental_quantity:
          description: '`null` means no quantity constraint.'
          type:
            - integer
            - 'null'
          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:
        - subscription_plan_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:
        subscription_plan_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
            - Bimonthly
            - Monthly
            - Quarterly
            - Semiannually
            - Annually
          examples:
            - Monthly
        billing_limit:
          description: '`null` means unlimited billing cycles.'
          type:
            - integer
            - 'null'
        fulfill_separately:
          type: boolean
          default: false
        order_interval:
          description: >-
            order interval defines the frequency of when the subscription sends
            customers the product
          type:
            - integer
            - 'null'
        order_frequency:
          type:
            - string
            - 'null'
          enum:
            - Weekly
            - Bimonthly
            - Monthly
            - Quarterly
            - Semiannually
            - Annually
            - null
          examples:
            - Monthly
        order_limit:
          description: '`null` means unlimited fulfillment cycles.'
          type:
            - integer
            - 'null'
        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: '#/components/schemas/DiscountBasedPromotion'
              fixed-price: '#/components/schemas/FixedPricePromotion'
              volume-based: '#/components/schemas/VolumeBasedPromotion'
              free-goods: '#/components/schemas/FreeGoodsPromotion'
          oneOf:
            - $ref: '#/components/schemas/DiscountBasedPromotion'
            - $ref: '#/components/schemas/FixedPricePromotion'
            - $ref: '#/components/schemas/VolumeBasedPromotion'
            - $ref: '#/components/schemas/FreeGoodsPromotion'
    ProductShipping:
      title: ProductShipping
      type:
        - object
        - 'null'
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/ProductShipping
        description: API reference for the ProductShipping schema
      required:
        - handling_charges_including_tax
        - handling_charges_excluding_tax
        - tax_type
        - tax_rate
      properties:
        handling_charges_including_tax:
          type: number
        handling_charges_excluding_tax:
          type: number
        tax_type:
          type: string
        tax_rate:
          type: number
    Packaging:
      title: Packaging
      description: >-
        Packing dimensions for a product without variants. `null` when the
        product has variants, or when no packaging is configured.
      type:
        - object
        - 'null'
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Packaging
        description: API reference for the Packaging schema
      required:
        - pack_width
        - pack_height
        - pack_length
        - pack_dry_weight
        - units_per_pack
        - vertical_rotation
        - shipper_width
        - shipper_height
        - shipper_length
        - shipper_dry_weight
        - units_per_shipper
      properties:
        pack_width:
          type: number
          format: float
        pack_height:
          type: number
          format: float
        pack_length:
          type: number
          format: float
        pack_dry_weight:
          type: number
          format: float
        units_per_pack:
          type: integer
          format: int32
        vertical_rotation:
          description: >-
            Indicates whether items can be rotated during packing or must be
            kept in a strictly vertical orientation.
          type: boolean
        shipper_width:
          type:
            - number
            - 'null'
          format: float
        shipper_height:
          type:
            - number
            - 'null'
          format: float
        shipper_length:
          type:
            - number
            - 'null'
          format: float
        shipper_dry_weight:
          type:
            - number
            - 'null'
          format: float
        units_per_shipper:
          type:
            - integer
            - 'null'
          format: int32
        product_id:
          type:
            - string
            - 'null'
        product_variant_id:
          type:
            - string
            - 'null'
        product_name:
          type:
            - string
            - 'null'
        variant_name:
          type:
            - string
            - 'null'
      x-tags:
        - Catalog
    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:
          description: '`null` groups stock without a lot or batch.'
          type:
            - string
            - 'null'
        mfg_date:
          type:
            - string
            - 'null'
          format: date
        exp_date:
          type:
            - string
            - 'null'
          format: date
        manufacturer:
          type:
            - string
            - 'null'
        stock_quantity:
          type: number
    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
        - minimum_quantity
        - maximum_quantity
      properties:
        promotion_type:
          type: string
          const: discount
        discount_type:
          type: string
          enum:
            - percentage
            - fixed-amount
        discount_percent:
          description: Present only for percentage discounts.
          type: number
        discount_fixed_amount:
          description: Present only for fixed-amount discounts.
          type: integer
        minimum_quantity:
          type: integer
          minimum: 1
        maximum_quantity:
          type:
            - integer
            - 'null'
          minimum: 1
        maximum_discount_amount:
          description: >-
            Percentage discount cap; `null` means no cap. Omitted for
            fixed-amount discounts.
          type:
            - integer
            - 'null'
          minimum: 1
    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
        - minimum_quantity
        - maximum_quantity
      properties:
        promotion_type:
          type: string
          const: fixed-price
        offer_price:
          type: number
        minimum_quantity:
          type: integer
          minimum: 1
        maximum_quantity:
          type:
            - integer
            - 'null'
          minimum: 1
    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
          const: volume-based
        slabs:
          type: array
          items:
            type: object
            required:
              - quantity
              - quantity_condition
              - discount_percent
            properties:
              quantity:
                type: integer
              quantity_condition:
                description: >-
                  This key defines how the system will evaluate the quantity to
                  determine if the promotion should be applied, based on the
                  specified slab.
                enum:
                  - less
                  - less-or-equal
                  - greater
                  - greater-or-equal
              discount_percent:
                type: number
    FreeGoodsPromotion:
      title: FreeGoodsPromotion
      description: Supply `slab` or `slabs` for the free-goods quantities.
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/FreeGoodsPromotion
        description: API reference for the FreeGoodsPromotion schema
      required:
        - promotion_type
      properties:
        promotion_type:
          type: string
          const: free-goods
        auto_scale:
          type: boolean
        slab:
          $ref: '#/components/schemas/FreeGoodsSlab'
        slabs:
          type: array
          items:
            $ref: '#/components/schemas/FreeGoodsSlab'
          minItems: 1
    FreeGoodsSlab:
      title: FreeGoodsSlab
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/FreeGoodsSlab
        description: API reference for the FreeGoodsSlab schema
      required:
        - buy_quantity
        - get_quantity
        - quantity_condition
      properties:
        buy_quantity:
          type: integer
          minimum: 1
        get_quantity:
          type: integer
          minimum: 1
        quantity_condition:
          type: string
          enum:
            - less
            - less-or-equal
            - greater
            - greater-or-equal
  responses:
    BadRequest:
      description: Bad request
      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
              errors:
                type: object
              details:
                type: string
    Unauthorized:
      description: >-
        Authentication failed. Codes include `token-required`, `token-expired`
        and `token_not_valid` for an invalid or expired token.
      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
              details:
                type: string
    Forbidden:
      description: >-
        Access denied. `token-required` requires an authenticated session;
        `permission-denied` means the caller cannot access this resource. On
        POS, `session-expired` requires signing in again.
      content:
        application/json:
          schema:
            type: object
            required:
              - code
              - message
              - success
            properties:
              code:
                type: string
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              details:
                type: string
    InternalServerError:
      description: The request failed because of an unexpected error.
      content:
        application/json:
          schema:
            type: object
            required:
              - code
              - message
              - success
            properties:
              code:
                type: string
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              details:
                type: string
  securitySchemes:
    Authorization:
      type: http
      description: Access token
      scheme: bearer
    X-Api-Key:
      type: apiKey
      description: API key for your store
      name: X-Api-Key
      in: header

````

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