Filters
How to filter the products returned based on their attributes.
Filtering on attributes of the products returned from a request to the Clerk.io API is a powerful way to build a custom shopping experience for your customers.
Filters work by sending a filter string along with the request. The filter string is a simple condition whereby only products satisfying the conditions will be returned.
Notice: Pinning products with Merchandising will override filters.
Quick overview
Each filter consists of one or multiple simple expressions combined by logical operators and parenthesis to a filter condition. The simplest way to show this is by example:
brand = 'Imperial Inc.' and price > 100
on_sale = true or price < 49.95
tags contains 'Special Offer'
categories in [123, 456]
on_sale = false or (categories not in [123, 456] and price <= 200)
The Brand & Price filter example will only return products from the brand Imperial Inc. with a price above 100.
Filters are powerful - use with care
Only use filters on results where it makes sense for the customer. Filtering out potentially relevant products can harm the customer experience and your business.
Feel free to contact our Support Team at any time to get feedback on how to optimally use filters on your store.
Filter syntax in details
As mentioned above the filters are a combination of simple expressions. Any simple expressions must have the exact form attribute operator value (the simple in the name comes from this simplified format).
The attribute must be a product attribute name as defined in the product object when created. If the attribute isn't part of any product then the simple expression will match 0 products.
The operator has to be one of the operators described in the table below.
The value can be any valid attribute value.
| Operator | Meaning |
|---|---|
= | Match all products where the attribute is equal to value. |
!= | Match all products where the attribute is not equal to value. |
> | Match all products where the attribute is greater than value. |
>= | Match all products where the attribute is greater than or equal to value. |
< | Match all products where the attribute is less than value. |
<= | Match all products where the attribute is greater than or equal to value. |
contains | Match all products where the attribute is a list and value is in that list. |
contains not | Match all products where the attribute is a list and value is not in that list. |
in | Match all products where the attribute is equal to any value in value. valuecan both be a simple value and a value contained in a list. |
not in | Match all products where the attribute is not equal to any value in value. valuecan both be a simple value and a value contained in a list. |
The simple expressions described above can be combined into boolean conditions using parenthesis and the boolean operators and / or. Note that there is no negation operator.
Here is an example of a conditions:
expr1 or (expr2 and expr3)
price < 10 or (manufacturer = "Jedi" and age < 42)
The above condition is only true for products where either expr1 is true, or both expr2 and expr3 are true.
Filtering directly in API URLs
Filters can be added directly in the API URL using the filter parameter. An example could be to only display products with a price larger than 0, in case products with a price of 0 shouldn't be shown:
https://api.clerk.io/v2/search/search?key=PUBLIC_KEY&query=pizza&limit=99&filter=price+>+0
Dynamic filtering in embedcodes
Filters can also be used onsite in a JavaScript integration with the data-filter attribute. Using this method allows you to create filtering logics based on dynamic variables in the webshop.
An example could be to display products with a price equal to or above the amount that needs to be put in the basket to achieve free shipping. Assuming a webshop has the variable $free_shipping_limit, containing the remaining price, a dynamic filter could look like this:
<span class="clerk"
data-template="@complementary-to-basket"
data-filter="price > $free_shipping_limit">
</span>
Updated 15 days ago