Filtering

General

You can get a list of available filters and display the filter values along with the number of products for a specific filter.

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 walkthrough.

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

Get available filters

Retrieve a list of all applicable filters

You can retrieve 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

Param Name	Type	Required	Description
`where`	ProductSearchQuery	true	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. - `values` will include the available filter values and product counts for each filter. - `category_ids` will include the category filter (if available). List of parameters to include, for example: `isNew`, `styleGroup`.

Includes related resources of a filter in the response.

values will include the available filter values and product counts for each filter.
category_ids will include the category filter (if available). [/param]

List of parameters to include, for example: isNew, styleGroup.

Examples

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

See Authentication for how to set up.

This is currently only possible with the NodeJS SDK.

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 client.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 category specific filters

Usually products in different categories differ by their attributes. Shoe and Shirt sizes are defined in one dimension while a bra is split into two, cup and band sizes. That's why categories may also introduce different filters to be used by a user. Here we use the SDK to get the available filters for a specific category.

const filters = await client.filters.get({
  where: { categoryId: 1 },
});
const filterNames = filters.map(({ name }) => name);

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

Response

[
  {
    "id": null,
    "slug": "prices",
    "name": "Prices",
    "attributeGroupType": "computed_attribute",
    "type": "range",
    "values": [{ "min": 1990, "max": 10900, "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 }]
  },
  {
    "id": 1001,
    "slug": "color",
    "name": "Farbe",
    "attributeGroupType": "",
    "type": "attributes",
    "values": [
      { "name": "Schwarz", "productCount": 3, "id": 41, "value": "schwarz" },
      {
        "name": "Graumeliert",
        "productCount": 2,
        "id": 42,
        "value": "graumeliert"
      },
      {
        "name": "Dunkelblau",
        "productCount": 2,
        "id": 9,
        "value": "dunkelblau"
      },
      { "name": "Weiß", "productCount": 1, "id": 40, "value": "weiss" },
      {
        "name": "Dunkelgrau",
        "productCount": 1,
        "id": 43,
        "value": "dunkelgrau"
      },
      { "name": "Hellblau", "productCount": 1, "id": 51, "value": "hellblau" }
    ]
  },
  {
    "id": 550,
    "slug": "brand",
    "name": "Marke",
    "attributeGroupType": "",
    "type": "attributes",
    "values": [
      {
        "name": "Tommy Hilfiger",
        "productCount": 4,
        "id": 10,
        "value": "tommy_hilfiger"
      },
      {
        "name": "Tom Tailor",
        "productCount": 3,
        "id": 44,
        "value": "tom_tailor"
      },
      { "name": "Lewis", "productCount": 3, "id": 52, "value": "lewis" }
    ]
  }
]

Get a filter where the product name or attribute match 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 client.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 client.filters.get({
  where: {
    attributes: [
      {
        type: "attributes",
        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": 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 client.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: Schwarz
// 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": "Farbe",
    "attributeGroupType": "",
    "type": "attributes",
    "values": [
      { "name": "Weiß", "productCount": 1, "id": 40, "value": "weiss" },
      { "name": "Schwarz", "productCount": 1, "id": 41, "value": "schwarz" },
      {
        "name": "Graumeliert",
        "productCount": 1,
        "id": 42,
        "value": "graumeliert"
      },
      {
        "name": "Dunkelblau",
        "productCount": 1,
        "id": 9,
        "value": "dunkelblau"
      }
    ]
  },
  {
    "id": 550,
    "slug": "brand",
    "name": "Marke",
    "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 client.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": "Grey",
        "productCount": 1,
        "id": 42,
        "value": "grey"
      },
      {
        "name": "Navy",
        "productCount": 1,
        "id": 43,
        "value": "navy"
      },
      { "name": "blue", "productCount": 1, "id": 51, "value": "blue" },
      {
        "name": "Green",
        "productCount": 1,
        "id": 9,
        "value": "green"
      }
    ]
  },
  {
    "id": 550,
    "slug": "brand",
    "name": "Brand",
    "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

Param Name	Type	Required	Description
groupName	string	true	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 client.filters.getValues("prices", {
  where: options,
});

Response

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

Sale

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

Response

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

Category IDs

const options = { category: 6 };
const filters = await client.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 client.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 client.filters.getValues("isnew", {
  where: options,
});

Response

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