Overview
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.
Our Resource List | Online Store API (cart.com) shows available fields to create your search queries and filters.
How it works
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 (equal).
- value - The value being checked for. (Read here for additional information about using datetimes for this.)
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
These queries are searching for any products with the item name equal to test.
not
Returns results where the field is not equal to the supplied value.
/api/v1/products?item_name=not:test
This query is searching for any products with the item name not equal to test.
like
Returns results where a field contains the supplied value.
/api/v1/products?item_name=like:test
This query is searching for any products with the item name that includes test in it.
gt
Returns results where a field is greater than the supplied value.
/api/v1/products?price=gt:5.00
This query is searching for products with a price greater than 5.00.
gte
Returns results where a field is greater than or equal to the supplied value.
/api/v1/products?price=gte:5.00
This query is searching for products with a price greater than or equal to 5.00.
lt
Returns results where a field is less than the supplied value.
/api/v1/products?price=lt:25.00
This query is searching for products with a price less than 5.00.
lte
Returns results where a field is less than or equal to the supplied value.
/api/v1/products?price=lte:25.00
This query is searching for products with a price less than or equal to 5.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
These queries are searching for products with an item name of test AND a price that is greater than 5.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
The first query is searching for products with an item name that contains test OR a price that is less than or equal to 5.00.
The second query is searching for products with an item name that contains doge OR wow.
Sample Queries
This query will search for products with an item name equal to test.
/api/v1/products?item_name=test
This query will search for orders that were ordered after December 8th, 2012 at 6:00AM (UTC) and display the id, customer id, and grand total fields of all orders found.
/api/v1/orders?ordered_at=gt:2012-12-08T06:00:00.0Z&fields=id,customer_id, grand_total
This query will search categories for parent category id of 14 with a count of 10, and is on page 2.
/api/v1/categories?parent_category_id=14&count=10&page=2