Skip to main content
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.
In a POST, send the same string as filter_by:
In JavaScript, 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, true or false, or else a string. A number is digits with an optional leading - and decimal part, so 1e3 is a string.
  • A value in backticks is always a string. price:=`100` gets 400 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_by means no filter.
  • Joins such as $collection(...), geo filters, ! negation and exists are 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 named brand or category, which replaces the built-in one.
  • price and in_stock always mean the above.
  • Catalogue fields such as title, description, tags, product_type, gender, material and colors can 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 in var_color.value.
  • Any other name gets 400 unknown_filter_field, and allowed lists 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 with path: ["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 a checkbox of prices if you set it up that way. min is rounded down and max up. 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 radio from “20% or more” to “50% or more”, with values 0.2, 0.3, 0.4 and 0.5. Send discount:>=0.3 to select 30% or more. Only options with products are listed.
  • Sale and stock are a checkbox with the one value true.
  • 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 radio facet you set up yourself, which counts with every filter applied.
  • selected is true for 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.
The search rules apply to any request with a query, including a search inside a listing.

Sorts

Send sort=<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.