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

• A BigCommerce store (opens in a new tab).
• API access_token with information & settings modify scope.
• Knowledge of the Settings API.
• Pro or Enterprise store plan. To upgrade, see Changing Your Store's Plan (opens in a new tab).

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.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/search/filters
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: 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.

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 (opens in a new tab) or custom fields (opens in a new tab).

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

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/search/filters/available
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: 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.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/search/filters/available?channel_id=1&category_id={{CATEGORY_ID}}
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: 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.

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.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/settings/search/filters/contexts?channel_id=1&category_id={{CATEGORY_ID}}
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

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

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.

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.

You can also view the changes on the storefront.

Related resources

Articles

• Custom Fields (opens in a new tab)
• Product Filtering (opens in a new tab)

Endpoints

• Settings API
• Get All Categories