Thanks for being patient while we implement your feedback to improve the developer experience.

Get Enabled Filters

GET /settings/search/filters

Request

Returns a list of enabled default Product Filtering filters. These filters will be used if a store does not have contextual overrides.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/settings/search/filters' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

  • data    array[]

  • meta    object

    Response metadata.

example-1

{
  "data": [
    {
      "collapsed_by_default": false,
      "display_name": "Size",
      "display_product_count": true,
      "id": "U123=",
      "is_enabled": true,
      "items_to_show": 10,
      "sort_by": "alpha",
      "type": "product"
    },
    {
      "collapsed_by_default": false,
      "display_name": "Brand",
      "display_product_count": true,
      "id": "Y123=",
      "is_enabled": true,
      "items_to_show": 12,
      "sort_by": "alpha",
      "type": "brand"
    },
    {
      "collapsed_by_default": false,
      "display_name": "Color",
      "display_product_count": true,
      "id": "Q123=",
      "is_enabled": true,
      "items_to_show": 10,
      "sort_by": "alpha",
      "type": "product"
    },
    {
      "collapsed_by_default": true,
      "display_name": "Ships for Free",
      "display_product_count": false,
      "id": "Y456=",
      "is_enabled": true,
      "show_free_shipping_filter": true,
      "show_in_stock_filter": true,
      "show_is_featured_filter": true,
      "type": "other"
    }
  ],
  "meta": {}
}

Update Enabled Filters

PUT /settings/search/filters

Request

Updates enabled default Product Filtering filters.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

array | application/json
One of:

  • collapsed_by_default    boolean

  • display_name    string

  • display_product_count    boolean

  • id    string

  • is_enabled    boolean

  • items_to_show    integer

    Allowed: 5 | 10 | 15

  • sort_by    string

    Allowed: alpha | option_values | item_count

  • type    string

    Allowed: product

example-1

[
  {
    "collapsed_by_default": false,
    "display_name": "Size",
    "display_product_count": true,
    "id": "U123=",
    "is_enabled": true,
    "items_to_show": 12,
    "sort_by": "alpha",
    "type": "product"
  },
  {
    "collapsed_by_default": false,
    "display_name": "Brand",
    "display_product_count": true,
    "id": "Y123=",
    "is_enabled": true,
    "items_to_show": 10,
    "sort_by": "alpha",
    "type": "brand"
  },
  {
    "collapsed_by_default": false,
    "display_name": "Color",
    "display_product_count": true,
    "id": "Q123=",
    "is_enabled": true,
    "items_to_show": 10,
    "sort_by": "alpha",
    "type": "product"
  },
  {
    "collapsed_by_default": true,
    "display_name": "Ships for Free",
    "display_product_count": true,
    "id": "Y456=",
    "is_enabled": true,
    "show_free_shipping_filter": true,
    "show_in_stock_filter": true,
    "show_is_featured_filter": true,
    "type": "other"
  }
]

Response

Body

object | application/json

  • data

  • meta    object

    Response metadata.

example-1

{
  "data": [
    {
      "collapsed_by_default": false,
      "display_name": "Size",
      "display_product_count": true,
      "id": "U123==",
      "is_enabled": true,
      "items_to_show": 12,
      "sort_by": "alpha",
      "type": "product"
    },
    {
      "collapsed_by_default": false,
      "display_name": "Brand",
      "display_product_count": true,
      "id": "Y123=",
      "is_enabled": true,
      "items_to_show": 10,
      "sort_by": "alpha",
      "type": "brand"
    },
    {
      "collapsed_by_default": false,
      "display_name": "Color",
      "display_product_count": true,
      "id": "Q123=",
      "is_enabled": true,
      "items_to_show": 10,
      "sort_by": "alpha",
      "type": "product"
    },
    {
      "collapsed_by_default": true,
      "display_name": "Ships for Free",
      "display_product_count": true,
      "id": "Y456=",
      "is_enabled": true,
      "show_free_shipping_filter": true,
      "show_in_stock_filter": true,
      "show_is_featured_filter": true,
      "type": "other"
    }
  ],
  "meta": {}
}

Get Available Filters

GET /settings/search/filters/available

Request

Returns a list of filters available to power Product Filtering.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

  • channel_id in query - integer

    Narrows the list of available filters based on channel ID. Only products currently assigned to the given Channel will be considered.

  • category_id in query - integer

    Narrows the list of available filters based on category ID. You can display settings to show products from the provided category, subcategories only, or both the category and its child categories.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/settings/search/filters/available' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Response metadata.

example-1

{
  "data": [
    {
      "id": "Y2F0Zooo123=",
      "name": "Category",
      "product_count": 7,
      "type": "category"
    },
    {
      "id": "YnJh123=",
      "name": "Brand",
      "product_count": 8,
      "type": "brand"
    },
    {
      "id": "cmF0a123",
      "name": "Rating",
      "product_count": 1,
      "type": "rating"
    },
    {
      "id": "cHJp123=",
      "name": "Price",
      "price_range_max": 300.99,
      "price_range_min": 6.75,
      "type": "price"
    },
    {
      "id": "U2l123==",
      "name": "Size",
      "product_count": 3,
      "type": "product"
    },
    {
      "id": "Q29s123=",
      "name": "Color",
      "product_count": 2,
      "type": "product"
    },
    {
      "id": "Ym9123==",
      "name": "Other",
      "type": "other"
    }
  ],
  "meta": {}
}

Get Contextual Filters

GET /settings/search/filters/contexts

Request

Returns a list of contextual filters enabled for a particular channel or category.

Usage Notes

Contextual filters allow you to configure the enabled filters per channel or category, so that shoppers can filter by the most relevant criteria.

The order of the returned filters will match the sort order of the filters on the storefront.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • channel_id in query - integer

    Only return contextual overrides related to a particular Channel.

  • category_id in query - integer

    Only return contextual overrides related to a particular Category.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/settings/search/filters/contexts' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

OK

Body

object | application/json

  • data    array[object]

  • meta    object

example

{
  "data": [
    {
      "context": {
        "category_id": 0,
        "channel_id": 0
      },
      "data": [
        {
          "collapsed_by_default": true,
          "display_name": "string",
          "display_product_count": true,
          "id": "string",
          "is_enabled": true,
          "items_to_show": 5,
          "sort_by": "alpha",
          "type": "product"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "count": 5,
      "current_page": 1,
      "links": {
        "current": "?limit=5&page=1",
        "next": "?limit=5&page=2"
      },
      "per_page": 5,
      "total": 246,
      "total_pages": 50
    }
  }
}

Upsert Contextual Filters

PUT /settings/search/filters/contexts

Request

Upserts contextual filters for a particular channel or category.

Usage Notes

Contextual filters allow you to configure the enabled filters per channel or category, so that shoppers can filter by the most relevant criteria.

You can change the order of the filters on the live site by changing the order of the filters you send.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

array | application/json

  • context    object

  • data

example

{
  "context": {
    "category_id": 0,
    "channel_id": 0
  },
  "data": [
    {
      "collapsed_by_default": true,
      "display_name": "string",
      "display_product_count": true,
      "id": "string",
      "is_enabled": true,
      "items_to_show": 5,
      "sort_by": "alpha",
      "type": "product"
    }
  ]
}

Response

OK

Body

object | application/json

  • data    array[object]

  • meta    object

    Response metadata.

example

{
  "data": [
    {
      "context": {
        "category_id": 0,
        "channel_id": 0
      },
      "data": [
        {
          "collapsed_by_default": true,
          "display_name": "string",
          "display_product_count": true,
          "id": "string",
          "is_enabled": true,
          "items_to_show": 5,
          "sort_by": "alpha",
          "type": "product"
        }
      ]
    }
  ],
  "meta": {}
}