Filtering Syntax

When collections can be filtered you may pass one or more filter query parameters. The syntax for these filters is described below.

Basic Syntax (Equals)

The most basic filter is of the form key:value where key is the name of the field to filter by and value is a literal string or integer. This basic filter applies the logic “where equals ''”.

Query	Description
`?filter=id:15`	id equals 15
`?filter=status:complete`	status equals ‘complete’
`?filter=is_active:true`	boolean values `true` and `false` supported

Multiple filters can be specified in which case they are combined with a logical AND operation.

Query	Description
`?filter=id:15&filter=status:complete`	id equals 15 AND status equals ‘complete’

This basic syntax can be mixed with the advanced syntax described below.

Advanced Syntax

The advanced syntax is of the form key<json> where key is the field name and <json> is a valid JSON5 encoded object or array of objects. These objects can define a broad variety of conditions defined further below.

There is no : between the key and the <json>!

Query	Description
`?filter=id{gt:15}`	id greater than 15

AND Logic

Multiple conditions can be applied with AND logic for the same key by specifying multiple keys in the same JSON5 object.

Query	Description
`?filter=id{gt:15,lt:50}`	id greater than 15 AND less than 50

OR Logic

Multiple conditions can be applied with OR logic for the same key by specifying an array of objects.

Query	Description
`?filter=id[{lt:15},{gt:50}]`	id less than 15 OR greater than 50

Combined AND and OR logic

Both AND and OR logic can be used in the same filter.

Query	Description
`?filter=weight[{gt:1,lt:50},{null:true}]`	weight is either greater than 1 AND less than 50 OR weight is null

Multiple filters with advanced and simple syntax mixed

?filter=goods_type:NORMAL&filter=name[{start:"Box of"},{end:"CASE"}]&filter=id{gt:15}

Conditions

The following keys may be used within the JSON5 object to apply the described conditions.

key	Condition	Examples	Comment
eq	Equal to	`{eq:5}` `{eq:"John Doe"}` `{eq:true}`
neq	Not equal to	`{neq:5}` `{neq:"John Doe"}` `{eq:true}`
gt	Greater than	`{gt:5}`
lt	Less than	`{lt:5}`
gteq	Greater than or equal	`{gteq:5}`
lteq	Less than or equal	`{lteq:5}`
from	From date or date-time	`{from:"2021-11-17"}` `{from:"2021-11-17T14:32:44Z"}`	Specifying a date for a date-time value will be equivalent to “greater than or equal to YYYY-MM-DDT00:00:00Z” (inclusive)
to	To date or date-time	`{to:"2021-11-17"}` `{to:"2021-11-17T14:32:44Z"}`	Specifying a date for a date-time value will be equivalent to “less than or equal to YYYY-MM-DDT23:59:59Z” (inclusive)
start	Starts with	`{start:"John"}`	Prefix match (like `John*`)
end	Ends with	`{end:"Doe"}`	Suffix match (like `*Doe`)
contain	Contains anywhere	`{contain:"Baker"}`	Anywhere match (like `Baker`)
regex	Matches regular expression	`{regex:"^A.+Z$"}`	See MySQL Regular Expression Syntax
iregex	Matches regular expression (case insensitive)	`{regex:"^A.+Z$"}`	See MySQL Regular Expression Syntax
in	Equals a value in the set	`{in:[1,2,3,4]}` `{in:["canceled","processing"]}`
nin	Not equal to any value in the set	`{nin:[1,2,3,4]}` `{nin:["canceled","processing"]}`
null	Value is or is not NULL	`{null:true}` `{null:false}`
empty	Value is or is not NULL or equal to an empty string	`{empty:true}` `{empty:false}`	`true` is equivalent to `{eq:""},{null:true}` and `false` is equivalent to `{neq:"",null:false}`

String values must be "double-quoted" or 'single-quoted'.

Get Started

Common Features

Inventory API v1

Receiving API v1

Shipping API v1

System API v1

Basic Syntax (Equals)

Advanced Syntax

AND Logic

OR Logic

Combined AND and OR logic

Multiple filters with advanced and simple syntax mixed

Conditions

​Basic Syntax (Equals)

​Advanced Syntax

​AND Logic

​OR Logic

​Combined AND and OR logic

​Multiple filters with advanced and simple syntax mixed

​Conditions

Basic Syntax (Equals)

Advanced Syntax

AND Logic

OR Logic

Combined AND and OR logic

Multiple filters with advanced and simple syntax mixed

Conditions