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
Comments
3 comments
Is there a list of fields/fieldnames that this works with? Will it work with custom fields?
I tried the following, but it just returned every order after the specified date, and only included id, customer_id, and grand_total :
/api/v1/orders?ordered_at=gt:2019-05-03T06:00:00.0Z&SignatureRequiredForDelivery=Yes&fields=id,customer_id,grand_total,ServiceName
Hi Kathy,
I think for custom fields you can just include "custom_fields" in your list of fields to retrieve.
i.e. ...&fields=id,customer_id,grand_total,custom_fields
Then in the response, there will be a new array with the custom_fields and their values
For a list I would check their github:
https://github.com/AmeriCommerce/rest-api/blob/master/resources/orders.md
So a GET request to /api/v1/cart_items?item_number=widget123 works, but if I change the request to /api/v1/cart_items?item_number=widget123&price=lte:298.00, I get:
{
}
Does this mean I can't also filter by price for cart_items?
Please sign in to leave a comment.