Filters and Sorting
To implement filters and sorting options with the search products and content endpoint, you must first configure your desired filters and sorting options in Search Studio.
The filters and preSetFilters parameters are used across all product search endpoints:
Product Filters
Possible filter types for product search include: category, text (also known as multiselect), numeric, and Boolean. If there are products in the result set that match the configured filters, then these filters will be returned as filterOptions in the API response. The filters will be returned in the order defined in Search Studio.
If a filter option is configured and not being returned in the API response, check whether a "Show Above" percentage is set. This percentage, set to 0% by default, determines when a filter should be displayed. If the color filter is set to 20%, and only 15/100 results have a color value, then the color filter will not be displayed.
Each filter returned in the filterOptions array has a type.
- TREE: this type is used for category filters to indicate the filter can be displayed as a tree
- COLLECTION: this type is used for textual filters to indicate the filter can be displayed as a collection of possible filter values
- COLOR: this type is used for color filters and returns a hex code so that the filter values can be displayed as swatches if desired. (Note: To indicate a filter is a color filter, you must activate the "Treat as Color Filter" setting in Search Studio by editing the color filter option and checking this box.)
- RANGE: this type is used for numeric filters intended to be displayed as range filters. Each filter with this type will have minimum/maximum values as well as the counts for each value in between.
- BUCKET: this type is used for numeric filters intended to be displayed as buckets. This filter type can be configured in Search Studio to break numeric data into a desired number of buckets. The API response returns the number of products that fit into each bucket, and the bucket ranges. For example, a price filter using buckets might have 3 buckets for products ranging between $100-400: $100-200, $200-300, and $300-400.
- NUMERIC_VALUES: this type is used for numeric filters where each numeric value should be displayed as its own checkbox. This is useful in scenarios where there are a small number of numeric values and the desired behavior is to filter for an exact number. For example, if you want to filter for a notebook with 2 USB ports.
- BOOLEAN: this type is used for true/false filters
When a customer selects a filter option, you should send a new request with this filter set in the filters parameter.
The filters parameter expects a JSON array containing filters for product search OR content search (NOT both at the same time).
Filter Examples
Here are some examples for product filters (but remember to rely on the JSON response to ensure you are passing valid names and values):
To receive a list of possible filters in the search response, you must first configure your filter list in Search Studio.
CATEGORY (TREE)
[{"name":"Category", "type":"products", "values":[{"name":"Dishwashers"}]}]
COLLECTION (TEXT)
[{"name":"Certification", "type":"products", "values":[{"name":"Organic"}]}]
For text filters where customers can select multiple options at the same time, you will see that the filter option still appears in the filterOptions array after you have applied the first selected filter to the results. For example, if you have a filter "Certification", and a user clicks "Organic", send the request like in the example above. The products returned will be products with the certification "Organic." If some of those organic products also have a Fair Trade certification, then you will see in the filterOptions array that there are additional filter values relevant for the customer. If the customer then selects the filter "Fair Trade", your new request should include:
[{"name":"Certification", "type":"products", "values":[{"name":"Organic"},{"name":"Fair Trade"}]}]
This process can be repeated until there are no additional filter options available.
When multiple values are selected, the filter uses the logic configured in the filter settings in Search Studio (OR by default). You can override this per request by setting "logic": "AND" (require all values to match) or "logic": "OR" (match any value). The logic option applies to COLLECTION, COLOR, TREE, and NUMERIC_VALUES filter types.
[{"name":"Certification", "type":"products", "logic":"AND", "values":[{"name":"Organic"},{"name":"Fair Trade"}]}]
You can use "allValues": true on COLLECTION and BOOLEAN filters to match all products that have any value for that attribute, without specifying individual values:
[{"name":"Certification", "type":"products", "allValues": true}]
RANGE
[{"name":"Rating", "type":"products", "min":4.0, "max":5.0}]
BUCKET
[{"name":"Rating", "type":"products", "values":[{"name":"4.5 - 5.0"}]}]
NUMERIC_VALUES
[{"name":"Number of USB ports", "type":"products", "values":[{"value":"2"}]}]
BOOLEAN
[{"name":"Free Shipping", "type":"products", "values":[{"value":"true"}]}]
or using the booleanValue shorthand:
[{"name":"IS_ONLINE", "booleanValue": true}]
without — excluding products
Any filter type supports without. When true, products matching the filter are excluded:
[{"name":"Category", "type":"products", "without": true, "values":[{"value":"ROOT/Hidden"}]}]
Identifying Filters and Values
There are three ways to reference a filter (and its values) in a request: by conceptIdName, by display name, or by database id.
By conceptIdName (recommended)
Using conceptIdName is the preferred and most stable way to reference filters. Unlike display names, concept ID names are not affected by renaming or translation changes. Filters referenced by conceptIdName do not need to be configured in Search Studio, which makes them useful for programmatic filtering that should not be visible in the frontend. You can find conceptIdNames in the Data Platform or via the concept API endpoint.
[{"conceptIdName": "BRAND", "type":"products", "values":[{"conceptIdName": "BRAND_#_BRANDNAME"}]}]
By display name
You can also reference filters by their display name. All the examples earlier on this page use this approach. Note that display names can change when filters are renamed or translated, so integrations relying on them may be less stable.
[{"name":"Certification", "type":"products", "values":[{"name":"Organic"}]}]
By database ID
You can also reference filters and values by their database id.
[{"id":"277092785", "type":"products", "values":[{"id":"279261367"}]}]
Content Filters
We distinguish between product and content filters, and it is not possible to filter for both at the same time. If you have content pages in your search, such as blog articles, you can set up data points that can be used as content filters. A common data point might be publication date or tags/topics. Content filers are also configured in Search Studio under Filters and Sorting.
Here is an example for content search:
[{"name":"Topics", "type":"content", "values":[{"value":"Beach"}]}]
Pre-set Filters
Pre-set filters (preSetFilters) use the same JSON schema as filters, but with key differences:
- They are not visible to the end user — they cannot see or remove them on the frontend.
- They are used to pre-filter the product catalog for a specific integration, e.g., showing only available products, restricting to a specific assortment, or excluding certain categories.
- Conceptually similar to what a catalog does, but applied at search time.
Example: Show only products that are online, not end-of-life, in a specific assortment, and exclude certain categories:
[
{"name": "extendedAssortment", "values": [{"name": "LMR_ZI"}, {"name": "public"}]},
{"name": "END_OF_LIFE", "booleanValue": false},
{"name": "IS_ONLINE", "booleanValue": true},
{"name": "Category", "without": true, "values": [
{"value": "Online|catalog|cat_hidden_1"},
{"value": "Online|catalog|cat_hidden_2"}
]}
]
Sorting Products
Any numeric or Boolean attribute can be used to create a sorting option in Search Studio. Only sorting options that have been configured will work with the sort parameter. When configuring sorting options, you must create both the ascending and descending option if required (e.g., to sort by price in both directions.)
The sort parameter expects a string containing the name of the sorting option. For example, to sort by price from low to high, you might have configured this sorting option:
Price (low to high)
In your API request, you can activate this sorting option like this:
"sort": "Price (low to high)",
Similar to programmatic filtering option described above, you can sort by any numeric or Boolean attribute using the sortComplex parameter, even if the sorting option has not been configured in Search Studio.
sortComplex expects a JSON object containing the conceptIdName or key and a sorting direction (ASC for ascending, DESC for descending):
{"conceptIdName": "PRICE", "direction":"ASC"}
or
{"key": "277092657", "direction":"ASC"}
You can also use sortComplex to apply a different ranking strategy than the one used by default across all search queries. For this type of sorting, you need the rankingStrategyId from Search Studio. The parameter will look like this:
{"rankingStrategyId":"6672d6564f23963fbb4b0a78", "type":"STRATEGY"}
Sorting Content
If you have numeric or date data points, you can also set up sorting options for content pages in Search Studio.