AdminCatalog and Inventory

Contextual Filters

The Settings API allows you to manage settings and configurations for BigCommerce-hosted stores and headless storefronts.

You can use the Contextual Filters endpoint of the Settings API to programmatically configure a store’s Product Filtering feature, also known as faceted search. Additionally, the Contextual Filters endpoint enables you to merchandise diverse product catalogs by creating a different faceted search configuration for each channel and product category on a store. With this feature, you can configure the product categories for various product lines with a different set of enabled filters, so that shoppers can filter by the most relevant criteria.

This article demonstrates how to use Contextual Filters to configure filters that appear on a particular category page.

Limitations

  • Currently, the API only supports the default channel with an ID of 1.
  • At this time, you can configure contextual filters for Category pages, but not for Brand or Search Results pages.

Prerequisites

  • Your store plan must support Product Filtering to use contextual filters.
  • Product Filtering is available for Pro and Enterprise plans. To upgrade, see Changing Your Store’s Plan.
  • Enterprise accounts have the ability to use custom fields as product filters to provide shoppers with additional ways to customize their search.

View active storefront filters

There are two ways to retrieve your store’s currently active storefront filters:

  • Settings API
  • The store’s control panel

To view all configured filters using the API, send a GET request to /v3/settings/search/filters.

The response will contain all of the filters currently active on your store.

Example request: Get enabled filters
1GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/search/filters
2X-Auth-Token: {{ACCESS_TOKEN}}
3Accept: application/json

The filters returned from completing this GET request should match the filters you see in the control panel under Storefront Filters. This set of storefront filters is what you currently have configured on your store.

To access Storefront Filters in the control panel, go to Products Product Filtering.

Products Filters

View available storefront filters

The list of available storefront filters is derived from the product information in the catalog. You create new available filters by changing the product information in your catalog, such as adding new product options or custom fields.

To retrieve all available storefront filters, send a GET request to /v3/settings/search/filters/available.

Example request: Get available filters
1GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/search/filters/available
2X-Auth-Token: {{ACCESS_TOKEN}}
3Accept: application/json

View available category-level filters

To retrieve a list of filters available on a given category, include the category_id query parameter in your GET request to /v3/settings/search/filters/available. Currently, the Settings API only supports the default channel_id of 1.

Example request: Get available filters for a category
1GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/search/filters/available?channel_id=1&category_id={{CATEGORY_ID}}
2X-Auth-Token: {{ACCESS_TOKEN}}
3Accept: application/json

The filters returned from completing this GET request are the filters available for configuration on the given category. In this example, we have Brand, Rating, Price, Color, Size, and Other filters to pick from when choosing which filters to activate for the Kitchen category. In reality, you will be able to select from more filters.

To get a list of your store’s categories, send a GET request to /v3/catalog/categories.

View contextual filters

To see if there are any contextual overrides present on a given category, send a GET request to /v3/settings/search/filters/contexts specifying the category_id query parameter.

The response will contain the category’s existing contextual overrides.

Example request: Get contextual filters for a category
1GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/search/filters/contexts?channel_id=1&category_id={{CATEGORY_ID}}
2X-Auth-Token: {{ACCESS_TOKEN}}
3Accept: application/json

The order and names of returned filters should match the filters listed under Category Filters in the control panel.

Category Filters

The order of the data you send implicitly determines the sort order of the filters on the storefront. You can change the order of the filters on the live site by changing the order of the array’s data.

Configure contextual filters

Using the Contextual Filters endpoint, you can configure available category-level filters. To test it out, update some of your category’s properties such as display_name, display_product_count, or collapsed_by_default and send a PUT request to /v3/settings/search/filters/contexts.

Example request: Upsert contextual filters
PUT /stores/{{STORE_HASH}}/v3/settings/search/filters/contexts
Host: api.bigcommerce.com
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
[
  {
    "data": [
      {
        "id": "U2l6ZQ==",
        "display_name": "Kitchen Size",
        "type": "product",
        "display_product_count": false,
        "collapsed_by_default": true,
        "items_to_show": 5,
        "sort_by": "alpha",
        "is_enabled": false
      },
      {
        "id": "cHJpY2U=",
        "display_name": "Product Price",
        "type": "price",
        "collapsed_by_default": false,
        "is_enabled": true
      },
      {
        "id": "cmF0aW5n",
        "display_name": "Item Rating",
        "type": "rating",
        "collapsed_by_default": true,
        "is_enabled": true
      },
      {
        "id": "YnJhbmQ=",
        "display_name": "Brand",
        "type": "brand",
        "sort_by": "alpha",
        "items_to_show": 10,
        "collapsed_by_default": false,
        "display_product_count": true,
        "is_enabled": true
      },
      {
        "id": "Q29sb3I=",
        "display_name": "Color",
        "type": "product",
        "display_product_count": true,
        "collapsed_by_default": false,
        "items_to_show": 10,
        "sort_by": "alpha",
        "is_enabled": true
      },
      {
        "id": "Ym9vbA==",
        "display_name": "Other",
        "type": "other",
        "is_enabled": true,
        "display_product_count": true,
        "collapsed_by_default": true,
        "show_free_shipping_filter": true,
        "show_is_featured_filter": true,
        "show_in_stock_filter": true
      }
    ],
    "context": {
      "channel_id": 1,
      "category_id": 21
    }
  }
]

Refresh your store and open the category you just updated in the control panel.

Updated Category Filters

You can also view the changes on the storefront.

Updated Category Filters

  • You can add new filters using custom fields.
  • For information on how to manage filters using the control panel, see Product Filtering.
  • A storefront can display up to 12 filters per page.

Articles

Endpoints