Resource Query/Filtering Syntax

Follow

The query syntax is available on every resource root (i.e. /api/v1/products). It allows for more advanced filtering of the data returned. All field names (with the exception of nested resources) are available as query string parameters for this functionality. It can be combined with the other parameters that each endpoint supports.

The general format of a query syntax parameter is as follows:

/api/v1/resource/field_name=op:value
  • field_name - The name of the field that will be compared against.

  • op - (Optional) The comparison operator to use when comparing the specified value to the field. Defaults to eq.

  • value - The value being checked for. (Read here for additional information about using datetimes for this.)

Samples:

/api/v1/products?item_name=test
/api/v1/orders?ordered_at=gt:2012-12-08T06:00:00.0Z&fields=id,customer_id,grand_total
/api/v1/categories?parent_category_id=14&count=10&page=2

Comparison Operators

eq

This is the default if no operator is specified. Returns results where a field is equal to the supplied value.

/api/v1/products?item_name=test
/api/v1/products?item_name=eq:test
not

Returns results where a field is not equal to the supplied value.

/api/v1/products?item_name=not:test
like

Returns results where a field contains the supplied value.

/api/v1/products?item_name=like:test
gt

Returns results where a field is greater than the supplied value.

/api/v1/products?price=gt:5.00
gte

Returns results where a field is greater than or equal to the supplied value.

/api/v1/products?price=gte:5.00
lt

Returns results where a field is less than the supplied value.

/api/v1/products?price=lt:25.00
lte

Returns results where a field is less than or equal to the supplied value.

/api/v1/products?price=lte:25.00

Conjunction Operators

Complex queries using parentheses are not supported. The conjunctions we do support will be evaluated in the standard order of operations.

AND

The default when multiple fields are specified in a query. Can also be used to specify multiple comparison values for a single field.

/api/v1/products?item_name=test&price=gt:5.00
/api/v1/products?price=gt:5.00+AND+lte:25.00
OR

Can prefix the first operator, in which it overrides the default AND behavior and uses OR instead. It can also be used to specify multiple comparison values for a single field.

/api/v1/products?item_name=like:test&price=OR+lte:25.00
/api/v1/products?item_name=like:doge+OR+like:wow
Have more questions? Submit a request

Comments