Search products - Commerce Engine Docs

curl --request POST \
  --url https://staging.api.commercengine.io/api/v1/{store_id}/storefront/catalog/marketplace/products/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "shoes",
  "filter": "product_type IN [physical,bundle]"
}
'

{
  "message": "<string>",
  "success": true,
  "content": {
    "skus": [
      {
        "product_id": "<string>",
        "variant_id": "<string>",
        "sku": "<string>",
        "product_slug": "<string>",
        "variant_slug": "<string>",
        "product_name": "<string>",
        "variant_name": "<string>",
        "short_description": "<string>",
        "active": true,
        "stock_available": true,
        "on_subscription": true,
        "on_promotion": true,
        "category_ids": [
          "<string>"
        ],
        "tags": [
          "<string>"
        ],
        "reviews_count": 123,
        "reviews_rating_sum": 123,
        "attributes": [
          {
            "id": "<string>",
            "name": "<string>",
            "key": "<string>",
            "type": "color",
            "value": [
              {
                "name": "<string>",
                "hexcode": "<string>"
              }
            ]
          }
        ],
        "images": [
          {
            "id": "<string>",
            "title": "<string>",
            "alternate_text": "<string>",
            "sort_order": 123,
            "url_tiny": "<string>",
            "url_thumbnail": "<string>",
            "url_standard": "<string>",
            "url_zoom": "<string>"
          }
        ],
        "pricing": {
          "currency": "<string>",
          "tax_type": "GST",
          "tax_rate": 123,
          "price_including_tax": true,
          "listing_price": 123,
          "selling_price": 123,
          "min_order_quantity": 1,
          "max_order_quantity": 123,
          "incremental_quantity": 1,
          "selling_price_excluding_tax": 123
        },
        "promotion": {
          "id": "<string>",
          "starts_at": "2023-11-07T05:31:56Z",
          "expires_at": "2023-11-07T05:31:56Z",
          "details": {
            "discount_percent": 123,
            "discount_fixed_amount": 123
          }
        },
        "subscription": [
          {
            "id": "<string>",
            "subscription_plan": "<string>",
            "subscription_price": 123,
            "billing_interval": 123,
            "billing_limit": 123,
            "fulfill_separately": false,
            "order_interval": 123,
            "order_limit": 123,
            "minimum_quantity": 123,
            "billing_trial_days": 123
          }
        ],
        "associated_options": {
          "background_color": {
            "name": "Background Color",
            "value": {
              "name": "Blue",
              "hexcode": "#0000FF"
            },
            "type": "color"
          },
          "size": {
            "name": "Size",
            "value": "Large",
            "type": "single-select"
          }
        },
        "seller_id": "<string>",
        "seller_detail": {
          "id": "<string>",
          "trade_name": "<string>",
          "legal_name": "<string>",
          "business_type": "<string>",
          "tax_identification_number": "<string>"
        },
        "backorder": true,
        "categories": [
          {
            "id": "<string>",
            "name": "<string>",
            "slug": "<string>",
            "description": "<string>",
            "parent_category_id": "<string>",
            "product_count": 123,
            "active": true
          }
        ],
        "shipping": {
          "handling_charges_including_tax": 123,
          "handling_charges_excluding_tax": 123,
          "tax_type": "<string>",
          "tax_rate": 123
        },
        "inventory": [
          {
            "lot_batch": "<string>",
            "mfg_date": "2023-12-25",
            "exp_date": "2023-12-25",
            "manufacturer": "<string>",
            "stock_quantity": 123
          }
        ]
      }
    ],
    "facet_distribution": {},
    "facet_stats": {},
    "pagination": {
      "total_records": 123,
      "total_pages": 123,
      "limit": 123,
      "next_page": 123,
      "previous_page": 123
    }
  }
}

{
  "message": "<string>",
  "success": false,
  "code": "<string>"
}

POST

catalog

marketplace

products

curl --request POST \
  --url https://staging.api.commercengine.io/api/v1/{store_id}/storefront/catalog/marketplace/products/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "shoes",
  "filter": "product_type IN [physical,bundle]"
}
'

{
  "message": "<string>",
  "success": true,
  "content": {
    "skus": [
      {
        "product_id": "<string>",
        "variant_id": "<string>",
        "sku": "<string>",
        "product_slug": "<string>",
        "variant_slug": "<string>",
        "product_name": "<string>",
        "variant_name": "<string>",
        "short_description": "<string>",
        "active": true,
        "stock_available": true,
        "on_subscription": true,
        "on_promotion": true,
        "category_ids": [
          "<string>"
        ],
        "tags": [
          "<string>"
        ],
        "reviews_count": 123,
        "reviews_rating_sum": 123,
        "attributes": [
          {
            "id": "<string>",
            "name": "<string>",
            "key": "<string>",
            "type": "color",
            "value": [
              {
                "name": "<string>",
                "hexcode": "<string>"
              }
            ]
          }
        ],
        "images": [
          {
            "id": "<string>",
            "title": "<string>",
            "alternate_text": "<string>",
            "sort_order": 123,
            "url_tiny": "<string>",
            "url_thumbnail": "<string>",
            "url_standard": "<string>",
            "url_zoom": "<string>"
          }
        ],
        "pricing": {
          "currency": "<string>",
          "tax_type": "GST",
          "tax_rate": 123,
          "price_including_tax": true,
          "listing_price": 123,
          "selling_price": 123,
          "min_order_quantity": 1,
          "max_order_quantity": 123,
          "incremental_quantity": 1,
          "selling_price_excluding_tax": 123
        },
        "promotion": {
          "id": "<string>",
          "starts_at": "2023-11-07T05:31:56Z",
          "expires_at": "2023-11-07T05:31:56Z",
          "details": {
            "discount_percent": 123,
            "discount_fixed_amount": 123
          }
        },
        "subscription": [
          {
            "id": "<string>",
            "subscription_plan": "<string>",
            "subscription_price": 123,
            "billing_interval": 123,
            "billing_limit": 123,
            "fulfill_separately": false,
            "order_interval": 123,
            "order_limit": 123,
            "minimum_quantity": 123,
            "billing_trial_days": 123
          }
        ],
        "associated_options": {
          "background_color": {
            "name": "Background Color",
            "value": {
              "name": "Blue",
              "hexcode": "#0000FF"
            },
            "type": "color"
          },
          "size": {
            "name": "Size",
            "value": "Large",
            "type": "single-select"
          }
        },
        "seller_id": "<string>",
        "seller_detail": {
          "id": "<string>",
          "trade_name": "<string>",
          "legal_name": "<string>",
          "business_type": "<string>",
          "tax_identification_number": "<string>"
        },
        "backorder": true,
        "categories": [
          {
            "id": "<string>",
            "name": "<string>",
            "slug": "<string>",
            "description": "<string>",
            "parent_category_id": "<string>",
            "product_count": 123,
            "active": true
          }
        ],
        "shipping": {
          "handling_charges_including_tax": 123,
          "handling_charges_excluding_tax": 123,
          "tax_type": "<string>",
          "tax_rate": 123
        },
        "inventory": [
          {
            "lot_batch": "<string>",
            "mfg_date": "2023-12-25",
            "exp_date": "2023-12-25",
            "manufacturer": "<string>",
            "stock_quantity": 123
          }
        ]
      }
    ],
    "facet_distribution": {},
    "facet_stats": {},
    "pagination": {
      "total_records": 123,
      "total_pages": 123,
      "limit": 123,
      "next_page": 123,
      "previous_page": 123
    }
  }
}

{
  "message": "<string>",
  "success": false,
  "code": "<string>"
}

Authorizations

Authorization

string

header

required

Access token

Headers

x-customer-group-id

string

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.

Body

application/json

Payload for searching products.

query

string

required

String for searching products, considers the first ten words of any given search query.

page

integer

default:1

To request a specific page of results.

limit

integer

default:25

Maximum number of records returned for a page.

facets

string[]

provide list of attributes for specific facets or * for all facets. All attributes supported in the filter parameter are also supported here.

filter

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"]]

sort

string[]

Sort results by attributes. Use asc for ascending order and desc for descending order.

Examples:

"product_type:desc"

"product_name:asc"

Response

Success response

message

string

required

success

boolean

required

content

object

required

Show child attributes

Retrieve cross-sell products

Retrieve seller detail