browse narrows a search or a listing page with filter_by, a filter expression over your store’s field names. This page has the whole syntax.
Sending a filter
In a GET, percent-encode the whole value. A raw& ends the parameter, so && must be %26%26, and a literal + must be %2B.
filter_by:
URLSearchParams does the encoding for you:
Syntax
- A bare value ends at whitespace or any of
, ( ) [ ] & | `. Put any value with spaces or those characters in backticks:brand:=`Acme Outdoor`. - A bare value is a number,
trueorfalse, or else a string. A number is digits with an optional leading-and decimal part, so1e3is a string. - A value in backticks is always a string.
price:=`100`gets400 invalid_filter. - After a bare
:, a bare value with..in it is read as a range. Put it in backticks to match it as text. &&binds tighter than||. Use parentheses to group, up to 32 levels deep.- An empty
filter_bymeans no filter. - Joins such as
$collection(...), geo filters,!negation andexistsare not supported. Each gets a 400.
Operators
Fields you can filter on
When two fields share a name, the one higher in this table wins. The exception is a facet namedbrand or category, which replaces the built-in one.
priceandin_stockalways mean the above.- Catalogue fields such as
title,description,tags,product_type,gender,materialandcolorscan be filtered on only when they are one of your facets or filters. - A field name is letters, digits,
_and-, at most 128 characters. A facet on a nested attribute uses dots, as invar_color.value. - Any other name gets
400 unknown_filter_field, andallowedlists the names you can use. - A new field becomes filterable a few minutes after Depict indexes it.
Values per kind
Anything else gets
400 invalid_filter. That covers a comparison or range on a field that isn’t a number, a list after a comparison, a value of the wrong kind, and a range whose min is greater than its max.
Limits
Errors
Every filter error is a 400 withpath: ["filter_by"]. A syntax error names the character position.
Sometimes a field is allowed but your search index can’t filter on it, such as a facet that isn’t indexed. The API then drops the parts of your filter that use it and still serves the page. A dropped part is the whole
&& term that holds the field, so a group like (a || b) goes as one.
How your filter combines with Depict’s
The API applies your filter together with its own conditions, as(your filter) && (Depict's conditions). An || in your filter can’t bring back a product the API leaves out. Those are inactive products, products without a price or not sold in the market, hidden products, and products outside the listing.
Facets
Facets are the filters a shopper sees next to the results.browse returns them by default and with include=facets, in the order you set them up. A facet your search index can’t count is left out, and the others are still served.
Facet fields
Each value has the
value to send back in a filter, a label to show in the request’s language, a count and selected. A swatch value also has swatch, a CSS color, where you set one. Checkbox, radio and swatch values come most frequent first unless you set another order.
Values you group in your settings come back as one value. Its value is g_<group name>, its label is the group name, and its count covers every member. Send that value back to filter on the whole group.
Built-in facets
- Price is a
range, or acheckboxof prices if you set it up that way.minis rounded down andmaxup. They ignore the request’s own price filter. - Size is a
grid, in size order. On listing pages its counts are products in stock in that size, and without a filter, sizes out of stock show with count 0. On search its counts are all matching products with that size, unless your store hides out-of-stock products or the filter names the size. - Discount is a
radiofrom “20% or more” to “50% or more”, with values0.2,0.3,0.4and0.5. Senddiscount:>=0.3to select 30% or more. Only options with products are listed. - Sale and stock are a
checkboxwith the one valuetrue. - A category tree is a
hierarchy. Its labels are shown as stored.
Counts and selection
- Counts are products, meaning cards, not variants. They cover every product that matches, not just the page.
- When the filter selects values on a facet’s field alone, the facet’s other values show the counts they would have without that selection. A shopper can see what each extra value adds. This holds for every facet except a
radiofacet you set up yourself, which counts with every filter applied. selectedistruefor a value your filter selects with:=or:on that field alone. On the discount facet,:>=or:>with exactly one of its four values selects that option.- A value the shopper selected stays listed, at count 0 if needed, so the shopper can clear it. A category tree doesn’t re-add such values.
Facets that are left out
- A facet with no values is left out.
- On listing pages, so is a facet with one value and none selected. A category tree is kept.
- On search, so are a facet of only yes or no values and an unselected discount facet.
query, including a search inside a listing.
Sorts
Sendsort=<field>.<asc|desc> in a GET, or {"field", "order"} in a POST. Both parts are required. Leave sort out for the default order.
Any other field gets
400 unknown_sort_field, at path: ["sort", "field"], and allowed lists your sort fields. Pins keep their slots only with the default order or relevance, on a listing page without a query.
The sorts section of a browse response lists the sorts your store offers shoppers, which can be fewer than the fields above.
