POST
/
apis
/
ecommerce-service
/
public
/
discovery
/
v2
/
search
/
facet
Execute Faceted Product Search
curl --request POST \
  --url https://{base-address}/apis/ecommerce-service/public/discovery/v2/search/facet \
  --header 'Content-Type: application/json' \
  --data '{
  "search_term": "<string>",
  "category_id": "<string>",
  "collection_id": "<string>",
  "facets": [
    {
      "field_internal_name": "<string>",
      "value": "<string>"
    }
  ],
  "filter": [
    {
      "group": {
        "operator": "<string>",
        "rules": [
          {
            "action": "<string>",
            "field_name": "<string>",
            "value": "<string>"
          }
        ]
      }
    }
  ],
  "facet_fields": [
    {
      "field_name": "<string>",
      "display_name": "<string>",
      "type": "<string>"
    }
  ]
}'
{
  "Status": "success",
  "Data": {
    "facets": {
      "calculated_price": {
        "Price": {
          "buckets": [
            {
              "val": 123,
              "count": 123
            }
          ],
          "Price_min": 123,
          "Price_max": 123
        }
      },
      "brand": {
        "Brand": {
          "buckets": [
            {
              "val": "<string>",
              "count": 123
            }
          ]
        }
      },
      "option_size": {
        "Size": {
          "buckets": [
            {
              "val": "<string>",
              "count": 123
            }
          ]
        }
      },
      "option_color": {
        "Color": {
          "buckets": [
            {
              "val": "<string>",
              "count": 123
            }
          ]
        }
      }
    },
    "enabled_facets": [
      {
        "id": "<string>",
        "count": 123,
        "type": "<string>",
        "display_name": "<string>",
        "facet_type": "<string>",
        "field_name": "<string>",
        "sort_order": 123,
        "is_enabled": true,
        "show_count": true,
        "is_show_facet": 123,
        "display_as": "<string>",
        "field_sub_type": "<string>",
        "limit": 123
      }
    ],
    "_meta_": {
      "tenant_id": "<string>",
      "workspace_id": "<string>",
      "env_type": "<string>",
      "store_hash": "<string>",
      "content_model_id": "<string>",
      "_fields_": {}
    }
  }
}
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

​
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, includes metadata for each facet field.

​
show_all_facet_value
boolean

return all facet values whether they are enabled or disabled. When true, returns every possible facet value.

Body

application/json

Response

200
application/json

Faceted search results including matching products and facet metadata.

The response is of type object.