Product filters | Developer Guides

General

Filters allow you to quickly and easily narrow down a specific selection of products. You can find out how to retrieve a filtered list of products in the Searching Products by Their Attributes.

With the configured Storefront API (BAPI) client, you can:

retrieve a list of available filters that can then be used in product search
display filter values together with the quantity of products for a specific group of filters

Storefront API

Retrieve a list of available filters that can then be used in product search. There are default filters applicable for all categories as well as category-specific filters.

Parameters

Parameter	Type	Description
where	ProductSearchQuery	Accepts arbitrary filters based on the product specified attributes.
campaignKey	string	Used to get the correct prices for the specified campaign.
with	string	Includes related resources of a filter in the response.
including	string	List of parameters to include, for example: `isNew`, `styleGroup`.

Get default filters

To get a list of available default filters applicable to all categories we use the get method with empty parameters.

This is currently only possible with the NodeJS SDK.

// Get default filters
const filters = await adminApi.filters.get({});
const filterNames = filters.map(({ name }) => name);

console.log(filterNames);
// [ 'Prices', 'Sale', 'Savings' ]

Response

[
  {
    "id": null,
    "slug": "prices",
    "name": "Prices",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 1990, "max": 32990, "productCount": 14 }]
  },
  {
    "id": null,
    "slug": "sale",
    "name": "Sale",
    "attributeGroupType": "computed_attribute",
    "type": "boolean",
    "values": [
      { "name": false, "productCount": 14 },
      { "name": true, "productCount": 0 }
    ]
  },
  {
    "id": null,
    "slug": "max_savings_percentage",
    "name": "Savings",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 0, "max": 0, "productCount": 14 }]
  }
]

Get a filter with the product name or attribute matching a search term

We can pass a value for term to include only products in our filter request which contain that value within their name or their attributes.

const filters = await adminApi.filters.get({
  where: {
    term: "shirt",
  },
});

console.log(filters[0].values[0].productCount);
// 10

Response

[
  {
    "id": null,
    "slug": "prices",
    "name": "Prices",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 1990, "max": 3990, "productCount": 10 }]
  },
  {
    "id": null,
    "slug": "sale",
    "name": "Sale",
    "attributeGroupType": "computed_attribute",
    "type": "boolean",
    "values": [
      { "name": false, "productCount": 10 },
      { "name": true, "productCount": 0 }
    ]
  },
  {
    "id": null,
    "slug": "max_savings_percentage",
    "name": "Savings",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 0, "max": 0, "productCount": 10 }]
  }
]

Get a filter where the product name or attribute match a attribute value

Also we can pass a value for an attribute to include only products in our filter request which contain that value. In this case we filter for the brand Tommy Hilfiger. To get all available brand values beforehand see the example for filter values.

const filters = await adminApi.filters.get({
  where: {
    attributes: [
      {
        type: "attributes",
        key: "brand",
        values: [10], // Tommy Hilfiger
      },
    ],
  },
});

console.log(filters[0].values[0].productCount);

Response

[
  {
    "id": null,
    "slug": "prices",
    "name": "Prices",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 3990, "max": 3990, "productCount": 4 }]
  },
  {
    "id": null,
    "slug": "sale",
    "name": "Sale",
    "attributeGroupType": "computed_attribute",
    "type": "boolean",
    "values": [
      { "name": false, "productCount": 4 },
      { "name": true, "productCount": 0 }
    ]
  },
  {
    "id": null,
    "slug": "max_savings_percentage",
    "name": "Savings",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 0, "max": 0, "productCount": 4 }]
  }
]

Get filters for certain price range including campaign prices

Here we gonna get available filters for within a certain price range. We also pass a campaignKey to apply campaign prices to that request. This is of course optional and only relevant if there are active campaigns.

As a result we find that only one product has the color black in the price range between 20 and 60 euros. Without price range filter there are 3 black products.

const filters = await adminApi.filters.get({
  where: {
    minPrice: 2000,
    maxPrice: 6000,
    categoryId: 1,
  },
  campaignKey: "promo_test_20",
});

console.log(`color: ${filters[3].values[1].name}`);
console.log(`product count: ${filters[3].values[1].productCount}`);
// color: black
// product count: 1

Response

[
  {
    "id": null,
    "slug": "prices",
    "name": "Prices",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 1592, "max": 8720, "productCount": 10 }]
  },
  {
    "id": null,
    "slug": "sale",
    "name": "Sale",
    "attributeGroupType": "computed_attribute",
    "type": "boolean",
    "values": [
      { "name": true, "productCount": 4 },
      { "name": false, "productCount": 0 }
    ]
  },
  {
    "id": null,
    "slug": "max_savings_percentage",
    "name": "Savings",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 20, "max": 20, "productCount": 4 }]
  },
  {
    "id": 1001,
    "slug": "color",
    "name": "Color",
    "attributeGroupType": "",
    "type": "attributes",
    "values": [
      { "name": "White", "productCount": 1, "id": 40, "value": "white" },
      { "name": "Black", "productCount": 1, "id": 41, "value": "black" },
      {
        "name": "Grey",
        "productCount": 1,
        "id": 42,
        "value": "grey"
      },
      {
        "name": "Navy",
        "productCount": 1,
        "id": 9,
        "value": "navy"
      }
    ]
  },
  {
    "id": 550,
    "slug": "brand",
    "name": "Brand",
    "attributeGroupType": "",
    "type": "attributes",
    "values": [
      {
        "name": "Tommy Hilfiger",
        "productCount": 4,
        "id": 10,
        "value": "tommy_hilfiger"
      }
    ]
  }
]

Excluding products with filters

We can also apply a logical "not" operator to our filters to use them to exclude certain products. It's possible to exclude multiple attributes and even multiple values per attribute.

For example if we want to exclude all white and black products from Tommy Hilfiger we can do the following:

const filters = await adminApi.filters.get({
  where: {
    categoryId: 1,
    attributes: [
      {
        type: "attributes:not",
        key: "color",
        values: [41, 40], // black, white
      },
      {
        type: "attributes:not",
        key: "brand",
        values: [10], // Tommy Hilfiger
      },
    ],
  },
});

console.log(filters[0].values[0].productCount);
// 4

Response

[
  {
    "id": null,
    "slug": "prices",
    "name": "Prices",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 1990, "max": 10900, "productCount": 4 }]
  },
  {
    "id": null,
    "slug": "sale",
    "name": "Sale",
    "attributeGroupType": "computed_attribute",
    "type": "boolean",
    "values": [
      { "name": false, "productCount": 4 },
      { "name": true, "productCount": 0 }
    ]
  },
  {
    "id": null,
    "slug": "max_savings_percentage",
    "name": "Savings",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 0, "max": 0, "productCount": 4 }]
  },
  {
    "id": 1001,
    "slug": "color",
    "name": "color",
    "attributeGroupType": "",
    "type": "attributes",
    "values": [
      { "name": "black", "productCount": 2, "id": 41, "value": "black" },
      {
        "name": "heathergray",
        "productCount": 1,
        "id": 42,
        "value": "heathergray"
      },
      {
        "name": "navy",
        "productCount": 1,
        "id": 43,
        "value": "navy"
      },
      { "name": "lightblue", "productCount": 1, "id": 51, "value": "lightblue" },
      {
        "name": "navy",
        "productCount": 1,
        "id": 9,
        "value": "navy"
      }
    ]
  },
  {
    "id": 550,
    "slug": "brand",
    "name": "Marke",
    "attributeGroupType": "",
    "type": "attributes",
    "values": [
      {
        "name": "Tom Tailor",
        "productCount": 3,
        "id": 44,
        "value": "tom_tailor"
      },
      {
        "name": "Tommy Hilfiger",
        "productCount": 2,
        "id": 10,
        "value": "tommy_hilfiger"
      },
      { "name": "Lewis", "productCount": 1, "id": 52, "value": "lewis" }
    ]
  }
]

Get filter values

Display filter values and product counts.

You can retrieve the filter values and product counts for a specific filter groupName. At the moment, only a few filters are available via this endpoint, namely: sale, categoryids, savings, prices, brands, and isnew.

Also you can include additional product parameters in your search.

When isnew parameter is used, it is worth mentioning that products are considered new when they were inserted into the shop within a period of 28 days. This value can be adjusted accordingly for each shop.

Parameters

Parameter Details

groupName

Parameter	Details
groupName	String Filter name, only available values are: `sale`, `categoryids`, `savings`, `prices`, `brands`, `isnew`.
where	ProductSearchQuery Accepts arbitrary filters based on the product specified attributes.
campaignKey	String Used to get the correct prices for the specified campaign.

String

Filter name, only available values are: sale, categoryids, savings, prices, brands, isnew.

where

ProductSearchQuery

Accepts arbitrary filters based on the product specified attributes.

campaignKey

String

Used to get the correct prices for the specified campaign.

Examples

All examples require a configured Storefront API client being available as client.

See Authentication for how to set up.

In the following examples we fetch the filter values for all filter groups. We pass a categoryId, in this case of Women/Clothing and the name of the group.

The examples illustrate the different response structures depending on the requested filter. Please take a look at the response sections.

This is currently only possible with the NodeJS SDK.

Prices

const options = { category: 6 };
const filters = await adminApi.filters.getValues("prices", {
  where: options,
});

Response

[
  {
    "min":1990,
    "max":32990,
    "productCount":14
  }
]

Sale

const options = { category: 6 };
const filters = await adminApi.filters.getValues("sale", {
  where: options,
});

Response

[
  { "name": false, "productCount": 14 },
  { "name": true, "productCount": 0 }
]

Category Ids

const options = { category: 6 };
const filters = await adminApi.filters.getValues("categoryids", {
  where: options,
});

Response

[
  { "productCount": 10, "id": 1 },
  { "productCount": 7, "id": 12 },
  { "productCount": 7, "id": 13 },
  { "productCount": 3, "id": 8 }
]

Savings

const options = { category: 6 };
const filters = await adminApi.filters.getValues("savings", {
  where: options,
});

Response

[{ "min": 0, "max": 0, "productCount": 14 }]

Brands

const options = { category: 6 };
const filters = await adminApi.filters.getValues("brands", {
  where: options,
});

Response

[
  { "name": "Lewis", "productCount": 6, "id": 52, "value": "lewis" },
  {
    "name": "Tommy Hilfiger",
    "productCount": 4,
    "id": 10,
    "value": "tommy_hilfiger"
  },
  { "name": "Tom Tailor", "productCount": 3, "id": 44, "value": "tom_tailor" },
  { "name": "Liu Jo", "productCount": 1, "id": 78, "value": "liu_jo" }
]

Is New

const options = { category: 6 };
const filters = await adminApi.filters.getValues("isnew", {
  where: options,
});

Response

[
  { "name": false, "productCount": 14 },
  { "name": true, "productCount": 0 }
]