The Clerk.io Developer Hub

Welcome to the Clerk.io developer hub.

This is site is only technical specification for developers.

You'll find comprehensive guides and documentation to help you start working with Clerk.io at our Help Center

Get Started    

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.

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.

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>

Filters


How to filter the products returned based on their attributes.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.