Operators

Every attribute belongs to one of five filter categories. The category determines which operators are valid.

Category	Attribute types
`text`	plain text, HTML text, URL, color, country, identifier, taxonomy, options
`preset`	select, metaobject, category, image, boolean, product reference, variant reference
`numeric`	number, price, weight, dimension, volume
`datetime`	date-time
`date`	date

Operator matrix

Operator	text	preset	numeric	datetime	date
`EQUALS`	✓		✓	✓	✓
`NOT_EQUALS`			✓
`CONTAINS`	✓
`NOT_CONTAINS`	✓
`BEGINS_WITH`	✓
`IN`		✓
`NOT_IN`		✓
`GREATER_THAN`			✓
`LESS_THAN`			✓
`BEFORE`				✓	✓
`AFTER`				✓	✓
`IN_THE_LAST`				✓	✓
`NOT_IN_THE_LAST`				✓	✓
`EMPTY`	✓	✓	✓	✓	✓
`NOT_EMPTY`	✓	✓	✓	✓	✓

The value field's expected JSON shape depends on the operator.

Operator(s)	Value type	Notes
`EQUALS`, `CONTAINS`, `NOT_CONTAINS`, `BEGINS_WITH` (text)	string	Plain string match — `CONTAINS` and `BEGINS_WITH` are case-insensitive.
`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `LESS_THAN` (numeric)	number	For price attributes, the value is in the major currency unit (e.g. `100` means 100 USD, not 100 cents).
`BEFORE`, `AFTER`, `EQUALS` (datetime)	string	RFC3339 (`2024-01-15T00:00:00Z`).
`BEFORE`, `AFTER`, `EQUALS` (date)	string	`YYYY-MM-DD`.
`IN_THE_LAST`, `NOT_IN_THE_LAST`	string	Duration like `7d`, `24h`, `30d`.
`IN`, `NOT_IN`	array of strings	For preset attributes, the array contains the identifiers of the referenced entities (the same identifiers you'd use elsewhere in the API).
`EMPTY`, `NOT_EMPTY`	omit	The `value` field is not used.

Text contains:

{ "product.description": [{ "operator": "CONTAINS", "value": "organic" }] }

Numeric range — two entries on the same key combine as AND within the key:

{ "product.price": [
  { "operator": "GREATER_THAN", "value": 100 },
  { "operator": "LESS_THAN", "value": 500 }
] }

Preset IN:

{ "product.color": [{ "operator": "IN", "value": ["red", "blue"] }] }

Recent updates:

{ "_updated_at": [{ "operator": "IN_THE_LAST", "value": "7d" }] }

Missing attribute:

{ "product.description": [{ "operator": "EMPTY" }] }