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

# Search products

> Search for products matching a specific words or characters given.



## OpenAPI

````yaml https://openapi.commercengine.io/ce-storefront.json post /catalog/products/search
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/search:
    post:
      tags:
        - Products
      summary: Search products
      description: Search for products matching a specific words or characters given.
      operationId: search-products
      parameters:
        - $ref: '#/components/parameters/CustomerGroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchProduct'
            examples:
              in-operator:
                summary: IN operator (string)
                value:
                  query: shoes
                  filter: product_type IN [physical,bundle]
              and-string:
                summary: AND via string
                value:
                  query: shoes
                  filter: rating > 4 AND product_type = physical
              or-string:
                summary: OR via string
                value:
                  query: shoes
                  filter: product_type = physical OR product_type = bundle
              and-array:
                summary: AND via array
                value:
                  query: shoes
                  filter:
                    - rating > 4
                    - product_type = physical
              or-nested-array:
                summary: OR via nested array
                value:
                  query: shoes
                  filter:
                    - - product_type = physical
                      - product_type = bundle
              mixed-and-or:
                summary: AND + OR mixed
                value:
                  query: shoes
                  filter:
                    - product_type = physical
                    - - product_type = bundle
                      - rating > 4
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - success
                  - content
                properties:
                  message:
                    type: string
                  success:
                    type: boolean
                  content:
                    properties:
                      skus:
                        type: array
                        items:
                          $ref: '#/components/schemas/Item'
                      facet_distribution:
                        type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: integer
                      facet_stats:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            min:
                              type: number
                            max:
                              type: number
                          required:
                            - min
                            - max
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                    required:
                      - skus
                      - facet_distribution
                      - facet_stats
                      - pagination
                    type: object
          links:
            AddItemToCart:
              operationId: update-cart
              requestBody:
                product_id: $response.body#/content/skus/0/product_id
                variant_id: $response.body#/content/skus/0/variant_id
              description: Add a search result to a cart.
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - success
                properties:
                  message:
                    type: string
                    x-speakeasy-error-message: true
                  success:
                    type: boolean
                  code:
                    type: string
                  errors:
                    anyOf:
                      - type: object
                        additionalProperties: true
                      - type: string
                  content:
                    type: object
                    additionalProperties: true
        '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/search-products
        description: API reference for the search-products 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:
    SearchProduct:
      title: SearchProduct
      description: Payload for searching products.
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/SearchProduct
        description: API reference for the SearchProduct schema
      required:
        - query
      properties:
        query:
          description: >-
            String for searching products, considers the first ten words of any
            given search query.
          type: string
        page:
          description: To request a specific page of results.
          type: integer
          default: 1
        limit:
          description: Maximum number of records returned for a page.
          type: integer
          default: 25
        facets:
          description: >-
            provide list of attributes for specific facets or * for all facets.
            All attributes supported in the filter parameter are also supported
            here.
          type: array
          items:
            type: string
        filter:
          description: >-
            Filter expression(s) to narrow results. Omit for no filtering.


            **Syntax:** `attribute OPERATOR value`


            **Operators:**


            | Operator | Description | Example |

            |---|---|---|

            | `=` | Equal to | `product_type = physical` |

            | `!=` | Not equal to | `product_type != bundle` |

            | `>`, `>=`, `<`, `<=` | Comparison | `rating > 4` |

            | `TO` | Inclusive range (`>=` AND `<=`) | `pricing.selling_price
            100 TO 500` |

            | `IN [...]` | Matches any value in the list | `product_type IN
            [physical,bundle]` |

            | `NOT IN [...]` | Excludes all values in the list | `product_type
            NOT IN [physical,bundle]` |

            | `EXISTS` | Attribute is present (even if `null` or empty) | `tags
            EXISTS` |

            | `NOT EXISTS` | Attribute is absent | `tags NOT EXISTS` |

            | `IS NULL` | Value is `null` | `variant_id IS NULL` |

            | `IS NOT NULL` | Value is not `null` | `variant_id IS NOT NULL` |

            | `IS EMPTY` | Value is `""`, `[]`, or `{}` | `tags IS EMPTY` |

            | `IS NOT EMPTY` | Value is not empty | `tags IS NOT EMPTY` |

            | `AND` | Both conditions must match | `rating > 4 AND product_type
            = physical` |

            | `OR` | Either condition must match | `product_type = physical OR
            product_type = bundle` |

            | `NOT` | Negates a condition | `NOT product_type = bundle` |


            **Important rules:**

            - Operators are **case-sensitive** — must be uppercase (`AND`, not
            `and`).

            - String value comparison is **case-insensitive** — `product_type =
            Physical` matches `physical`.

            - Operator precedence: `NOT` > `AND` > `OR`. Use parentheses to
            override.

            - String values containing whitespace must be wrapped in single
            quotes.

            - `IN` takes comma-separated values in square brackets.

            - Maximum array nesting depth is **2 levels**.


            **Supported attributes:** `product_type`, `categories.name`,
            `attributes.key`, `pricing.listing_price`, `pricing.selling_price`,
            `pricing.tax_rate`, `product_id`, `variant_id`, `product_name`,
            `variant_name`, `tags`, `sku`, `stock_available`, `rating`


            **Combining conditions:**

            - **String:** Use `AND`/`OR` operators inline — `"rating > 4 AND
            product_type = physical"`

            - **Array of strings:** Conditions are combined with AND — `["rating
            > 4", "product_type = physical"]`

            - **Nested arrays:** Inner arrays express OR, outer array expresses
            AND — `["product_type = physical", ["product_type = bundle", "rating
            > 4"]]`
          oneOf:
            - type: string
            - type: array
              items:
                oneOf:
                  - type: string
                  - type: array
                    items:
                      type: string
        sort:
          description: >-
            Sort results by attributes. Use `asc` for ascending order and `desc`
            for descending order.
          type: array
          items:
            type: string
          examples:
            - product_type:desc
            - product_name:asc
    Item:
      title: SKU
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Item
        description: API reference for the Item schema
      required:
        - product_id
        - variant_id
        - sku
        - product_name
        - variant_name
        - product_type
        - short_description
        - active
        - stock_available
        - on_subscription
        - on_promotion
        - category_ids
        - tags
        - reviews_count
        - reviews_rating_sum
        - pricing
        - promotion
        - subscription
        - associated_options
      properties:
        product_id:
          type: string
        variant_id:
          type:
            - string
            - 'null'
        sku:
          type:
            - string
            - 'null'
        product_slug:
          type: string
        variant_slug:
          type:
            - string
            - 'null'
        product_name:
          type: string
        variant_name:
          type:
            - string
            - 'null'
        product_type:
          type: string
          enum:
            - physical
            - digital
            - bundle
          examples:
            - physical
        short_description:
          type:
            - string
            - 'null'
        active:
          type: boolean
        stock_available:
          type: boolean
        on_subscription:
          type: boolean
        on_promotion:
          type: boolean
        category_ids:
          type: array
          items:
            type: string
        categories:
          description: Expanded category objects.
          type: array
          items:
            $ref: '#/components/schemas/Category'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        reviews_count:
          description: >-
            Number of approved reviews; pending, rejected and archived reviews
            are excluded.
          type: integer
        reviews_rating_sum:
          description: >-
            Sum of approved review ratings, preserving fractional ratings. Zero
            when there are no approved reviews. Divide by reviews_count when
            nonzero to compute the average.
          type:
            - number
            - 'null'
          format: double
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/ProductAttribute'
        images:
          type: array
          items:
            $ref: '#/components/schemas/ProductImage'
        pricing:
          description: >-
            Pricing for the applicable customer group. `null` when no pricing is
            configured.
          oneOf:
            - $ref: '#/components/schemas/ProductPricing'
            - type: 'null'
        promotion:
          $ref: '#/components/schemas/ProductPromotion'
        subscription:
          type: array
          items:
            $ref: '#/components/schemas/ProductSubscription'
        associated_options:
          oneOf:
            - $ref: '#/components/schemas/AssociatedOption'
              description: Used when `variant_id` is not null.
            - type: 'null'
              description: Null when `variant_id` is null.
        shipping:
          $ref: '#/components/schemas/ProductShipping'
        slug:
          description: >-
            Slug of the returned entity (variant slug when `variant_id` is set,
            otherwise the product slug).
          type: string
        metadata:
          description: Freeform metadata key/value map.
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
        seo:
          oneOf:
            - $ref: '#/components/schemas/Seo'
            - type: 'null'
        hsn_code:
          description: HSN/SAC tax classification code. `null` when not configured.
          type:
            - string
            - 'null'
        on_offer:
          description: >-
            Indicates whether the item currently has an active offer. Emitted by
            the search-result variant of this payload.
          type: boolean
        packaging:
          $ref: '#/components/schemas/Packaging'
          description: >-
            Packing dimensions. Emitted by the search-result variant of this
            payload; `null` when none configured.
        inventory:
          type: array
          items:
            $ref: '#/components/schemas/LotBatchDetail'
      examples: []
    Pagination:
      description: pagination metadata structure
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Pagination
        description: API reference for the Pagination schema
      required:
        - total_records
        - total_pages
        - limit
        - next_page
        - previous_page
      properties:
        total_records:
          type: integer
        total_pages:
          type: integer
        previous_page:
          type:
            - integer
            - 'null'
        limit:
          type: integer
        next_page:
          type:
            - integer
            - 'null'
      examples:
        - total_records: 100
          total_pages: 4
          previous_page: null
          next_page: 2
          limit: 25
    Category:
      title: Category
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Category
        description: API reference for the Category schema
      required:
        - id
        - name
        - slug
        - description
        - parent_category_id
        - product_count
        - active
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
          readOnly: true
        slug:
          type: string
          readOnly: true
        description:
          type:
            - string
            - 'null'
        parent_category_id:
          type:
            - string
            - 'null'
          readOnly: true
        product_count:
          type: integer
        active:
          type: boolean
      examples: []
    ProductAttribute:
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/ProductAttribute
        description: API reference for the ProductAttribute schema
      discriminator:
        propertyName: type
        mapping:
          color: '#/components/schemas/ColorAttribute'
          single-select: '#/components/schemas/SingleSelectAttribute'
          multi-select: '#/components/schemas/MultiSelectAttribute'
          text: '#/components/schemas/TextAttribute'
          date: '#/components/schemas/DateAttribute'
          number: '#/components/schemas/NumberAttribute'
          boolean: '#/components/schemas/BooleanAttribute'
      oneOf:
        - $ref: '#/components/schemas/ColorAttribute'
          type: object
        - $ref: '#/components/schemas/SingleSelectAttribute'
          type: object
        - $ref: '#/components/schemas/MultiSelectAttribute'
          type: object
        - $ref: '#/components/schemas/TextAttribute'
          type: object
        - $ref: '#/components/schemas/DateAttribute'
          type: object
        - $ref: '#/components/schemas/NumberAttribute'
          type: object
        - $ref: '#/components/schemas/BooleanAttribute'
          type: object
    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: []
    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: []
    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'
    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: []
    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
    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
    Seo:
      title: Seo
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Seo
        description: API reference for the Seo schema
      required:
        - title
        - description
        - keywords
      properties:
        title:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        keywords:
          type:
            - array
            - 'null'
          items:
            type: string
        slug:
          type: string
    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
    ColorAttribute:
      title: ColorAttribute
      description: Attribute for colors
      type: object
      readOnly: true
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/ColorAttribute
        description: API reference for the ColorAttribute schema
      required:
        - id
        - name
        - key
        - type
        - value
      properties:
        id:
          type: string
        name:
          type: string
        key:
          description: >-
            A lookup safe version of the name that is lowercased and spaces are
            replaced with underscores. For instance, if name is `Product Type`,
            key will be `product_type`
          type: string
        type:
          type: string
          example: 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
          required:
            - name
            - hexcode
    SingleSelectAttribute:
      title: SingleSelectAttribute
      description: Attribute for single-select values
      type: object
      readOnly: true
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/SingleSelectAttribute
        description: API reference for the SingleSelectAttribute schema
      required:
        - id
        - name
        - key
        - type
        - value
      properties:
        id:
          type: string
        name:
          type: string
        key:
          description: >-
            A lookup safe version of the name that is lowercased and spaces are
            replaced with underscores. For instance, if name is `Product Type`,
            key will be `product_type`
          type: string
        type:
          type: string
          example: single-select
        value:
          description: For single-select attributes
          type: string
    MultiSelectAttribute:
      title: MultiSelectAttribute
      description: Attribute for multi-select values
      type: object
      readOnly: true
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/MultiSelectAttribute
        description: API reference for the MultiSelectAttribute schema
      required:
        - id
        - name
        - key
        - type
        - value
      properties:
        id:
          type: string
        name:
          type: string
        key:
          description: >-
            A lookup safe version of the name that is lowercased and spaces are
            replaced with underscores. For instance, if name is `Product Type`,
            key will be `product_type`
          type: string
        type:
          type: string
          example: multi-select
        value:
          description: For multi-select attributes
          type: array
          items:
            type: string
    TextAttribute:
      title: TextAttribute
      description: Attribute for text values
      type: object
      readOnly: true
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/TextAttribute
        description: API reference for the TextAttribute schema
      required:
        - id
        - name
        - key
        - type
        - value
      properties:
        id:
          type: string
        name:
          type: string
        key:
          description: >-
            A lookup safe version of the name that is lowercased and spaces are
            replaced with underscores. For instance, if name is `Product Type`,
            key will be `product_type`
          type: string
        type:
          type: string
          example: text
        value:
          description: For text attributes
          type: string
    DateAttribute:
      title: DateAttribute
      description: Attribute for date values
      type: object
      readOnly: true
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/DateAttribute
        description: API reference for the DateAttribute schema
      required:
        - id
        - name
        - key
        - type
        - value
      properties:
        id:
          type: string
        name:
          type: string
        key:
          description: >-
            A lookup safe version of the name that is lowercased and spaces are
            replaced with underscores. For instance, if name is `Product Type`,
            key will be `product_type`
          type: string
        type:
          type: string
          example: date
        value:
          description: >-
            `YYYY-MM-DD`, optionally followed by ` HH:MM`, ` HH:MM:SS`, or `
            HH:MM:SS.ffffff`.
          type: string
    NumberAttribute:
      title: NumberAttribute
      description: Attribute for numeric values
      type: object
      readOnly: true
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/NumberAttribute
        description: API reference for the NumberAttribute schema
      required:
        - id
        - name
        - key
        - type
        - value
      properties:
        id:
          type: string
        name:
          type: string
        key:
          description: >-
            A lookup safe version of the name that is lowercased and spaces are
            replaced with underscores. For instance, if name is `Product Type`,
            key will be `product_type`
          type: string
        type:
          type: string
          example: number
        value:
          description: For numeric attributes
          type: number
    BooleanAttribute:
      title: BooleanAttribute
      description: Attribute for boolean values
      type: object
      readOnly: true
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/BooleanAttribute
        description: API reference for the BooleanAttribute schema
      required:
        - id
        - name
        - key
        - type
        - value
      properties:
        id:
          type: string
        name:
          type: string
        key:
          description: >-
            A lookup safe version of the name that is lowercased and spaces are
            replaced with underscores. For instance, if name is `Product Type`,
            key will be `product_type`
          type: string
        type:
          type: string
          example: boolean
        value:
          description: For boolean attributes
          type: boolean
    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
    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
    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:
    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.