Search

Execute Product Search

curl --request POST \
  --url https://{base-address}/apis/ecommerce-service/public/discovery/v2/search \
  --header 'Content-Type: application/json' \
  --data '{
  "search_term": "<string>",
  "category_id": "<string>",
  "category_name": "<string>",
  "collection_id": "<string>",
  "facets": [
    {
      "field_internal_name": "<string>",
      "value": "<string>"
    }
  ],
  "filter": [
    {
      "group": {
        "operator": "<string>",
        "rules": [
          {
            "action": "<string>",
            "field_name": "<string>",
            "value": "<string>"
          }
        ]
      }
    }
  ],
  "out_of_stock": "INCLUDE",
  "session_id": "<string>",
  "user_id": "<string>"
}'

{
  "Status": "success",
  "Data": {
    "records": [
      {
        "id": "<string>",
        "content_model_id": "<string>",
        "variant_skus": [
          "<string>"
        ],
        "images": "<string>",
        "profit_percentage": 123,
        "conversion_rate": 123,
        "click_rate": 123,
        "revenue": 123,
        "categories": [
          "<string>"
        ],
        "brand": "<string>",
        "sku": "<string>",
        "name": "<string>",
        "description": "<string>",
        "is_featured": true,
        "calculated_price": 123,
        "sku_for_analytics": [
          "<string>"
        ],
        "reviews_rating_sum": 123,
        "reviews_count": 123,
        "variants": "<string>",
        "sale_price": 123,
        "page_slug": "<string>",
        "price": 123,
        "brand_page_slug": "<string>",
        "provider_id": "<string>",
        "provider_specific_data": "<string>",
        "variant_options": "<string>",
        "retail_price": 123,
        "pin": true,
        "slot": true,
        "include": true,
        "boost": true,
        "is_merchandising": true,
        "position": 123,
        "rule_details": [
          {}
        ]
      }
    ],
    "meta": {
      "STORE_HASH": "<string>",
      "ENV_TYPE": "<string>",
      "TENANT_ID": "<string>",
      "WORKSPACE_ID": "<string>",
      "_fields_": {
        "menu_title": {
          "type": "<string>",
          "sub_type": "<string>",
          "is_array": true,
          "is_searchable": true
        },
        "menu_description": {
          "type": "<string>",
          "sub_type": "<string>",
          "is_array": true,
          "is_searchable": true
        },
        "page_title": {
          "type": "<string>",
          "sub_type": "<string>",
          "is_array": true,
          "is_searchable": true
        }
      },
      "total_count": 123,
      "is_redirects": true,
      "redirect_url": "<string>",
      "did_you_mean": "<string>"
    }
  }
}

POST

apis

ecommerce-service

public

discovery

Execute Product Search

curl --request POST \
  --url https://{base-address}/apis/ecommerce-service/public/discovery/v2/search \
  --header 'Content-Type: application/json' \
  --data '{
  "search_term": "<string>",
  "category_id": "<string>",
  "category_name": "<string>",
  "collection_id": "<string>",
  "facets": [
    {
      "field_internal_name": "<string>",
      "value": "<string>"
    }
  ],
  "filter": [
    {
      "group": {
        "operator": "<string>",
        "rules": [
          {
            "action": "<string>",
            "field_name": "<string>",
            "value": "<string>"
          }
        ]
      }
    }
  ],
  "out_of_stock": "INCLUDE",
  "session_id": "<string>",
  "user_id": "<string>"
}'

{
  "Status": "success",
  "Data": {
    "records": [
      {
        "id": "<string>",
        "content_model_id": "<string>",
        "variant_skus": [
          "<string>"
        ],
        "images": "<string>",
        "profit_percentage": 123,
        "conversion_rate": 123,
        "click_rate": 123,
        "revenue": 123,
        "categories": [
          "<string>"
        ],
        "brand": "<string>",
        "sku": "<string>",
        "name": "<string>",
        "description": "<string>",
        "is_featured": true,
        "calculated_price": 123,
        "sku_for_analytics": [
          "<string>"
        ],
        "reviews_rating_sum": 123,
        "reviews_count": 123,
        "variants": "<string>",
        "sale_price": 123,
        "page_slug": "<string>",
        "price": 123,
        "brand_page_slug": "<string>",
        "provider_id": "<string>",
        "provider_specific_data": "<string>",
        "variant_options": "<string>",
        "retail_price": 123,
        "pin": true,
        "slot": true,
        "include": true,
        "boost": true,
        "is_merchandising": true,
        "position": 123,
        "rule_details": [
          {}
        ]
      }
    ],
    "meta": {
      "STORE_HASH": "<string>",
      "ENV_TYPE": "<string>",
      "TENANT_ID": "<string>",
      "WORKSPACE_ID": "<string>",
      "_fields_": {
        "menu_title": {
          "type": "<string>",
          "sub_type": "<string>",
          "is_array": true,
          "is_searchable": true
        },
        "menu_description": {
          "type": "<string>",
          "sub_type": "<string>",
          "is_array": true,
          "is_searchable": true
        },
        "page_title": {
          "type": "<string>",
          "sub_type": "<string>",
          "is_array": true,
          "is_searchable": true
        }
      },
      "total_count": 123,
      "is_redirects": true,
      "redirect_url": "<string>",
      "did_you_mean": "<string>"
    }
  }
}

Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See Authentication & Base URLs.

Headers

x-customer-group-id

string

Optional customer group identifier for segment-specific responses.

x-ecomm-provider

string

E-commerce provider for contextualizing the API call (e.g., shopify, magento, etc.).

Query Parameters

fields

string

required

Comma-separated list of fields to include in the response

locale

string

required

Specifies the language or region for the response data

store_id

string

Identifier of the store within the e-commerce platform.

channel_id

string

Sales or distribution channel identifier.

location_id

string

Identifier for the regional location from the BigCommerce admin panel.

currency

string

Currency code for price displays.

include_fields_meta

boolean

Whether to include metadata about the fields in the response. If true, include metadata for each searchable field.

include_count

boolean

Flag to include count in response. When true, returns total hit count alongside items.

skip

integer

Number of items to skip for pagination offset.

limit

integer

Maximum number of items to return.

sort_order

string

Order of sorting results (asc for ascending, desc for descending)

sort_by

string

Field to sort results by (e.g. price, popularity).

by_pass_merchandising

boolean

Whether to bypass merchandising rules for search. Set to true to ignore merchandising rules in ranking.

Body

application/json

search_term

string

Keyword or phrase to search across product titles and descriptions.

category_id

string

Identifier for the product category to filter results

category_name

string

Name of the product category to filter results

collection_id

string

Identifier for a specific collection or campaign

facets

object[]

Facet fields with value to filter product by color, size or provided facets

Show child attributes

filter

object[]

Query filter expression to narrow results

Show child attributes

out_of_stock

enum<string>

Controls inclusion of out-of-stock items. Whether to include/ exclude/ bury out-of-stock items

Available options:

INCLUDE,

EXCLUDE,

BURY

session_id

string

Identifier for the user's session id

user_id

string

Unique identifier for the user ID or user email

Response

Search results with product list and metadata.

Status

string

Example:

"success"

Data

object

Show child attributes

Get Asset By Id Search

⌘I

API Documentation

Management APIs

Delivery APIs

Headers

Query Parameters

Body

Response