Skip to main content
POST
/
catalog
/
marketplace
/
products
/
search
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>",
        "slug": "<string>",
        "product_name": "<string>",
        "variant_name": "<string>",
        "product_type": "physical",
        "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": {
            "promotion_type": "discount",
            "discount_type": "percentage",
            "discount_percent": 123,
            "discount_fixed_amount": 123
          }
        },
        "subscription": [
          {
            "id": "<string>",
            "subscription_plan": "<string>",
            "subscription_price": 123,
            "billing_interval": 123,
            "billing_frequency": "weekly",
            "billing_limit": 123,
            "fulfill_separately": false,
            "order_interval": 123,
            "order_frequency": "weekly",
            "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
    }
  }
}

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:

OperatorDescriptionExample
=Equal toproduct_type = physical
!=Not equal toproduct_type != bundle
>, >=, <, <=Comparisonrating > 4
TOInclusive range (>= AND <=)pricing.selling_price 100 TO 500
IN [...]Matches any value in the listproduct_type IN [physical,bundle]
NOT IN [...]Excludes all values in the listproduct_type NOT IN [physical,bundle]
EXISTSAttribute is present (even if null or empty)tags EXISTS
NOT EXISTSAttribute is absenttags NOT EXISTS
IS NULLValue is nullvariant_id IS NULL
IS NOT NULLValue is not nullvariant_id IS NOT NULL
IS EMPTYValue is "", [], or {}tags IS EMPTY
IS NOT EMPTYValue is not emptytags IS NOT EMPTY
ANDBoth conditions must matchrating > 4 AND product_type = physical
OREither condition must matchproduct_type = physical OR product_type = bundle
NOTNegates a conditionNOT 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.name, 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