REST API Query Parameters

You can use query parameters to control what data is returned in endpoint responses.

This section applies to both OSF . This section applies to Open Storefront Framework (OSF).

The sections below describe query parameters that you can use to control the set of items and properties in responses, and the order of the items returned.

Control the Set of Items Returned

To prevent the response from becoming too large, the number of items returned is limited by default to 250. You can override this value by using the limit query parameter to specify a different number. For example, the following call limits the number of orders returned to 5:
GET /ccadmin/v1/orders?limit=5
To page through the results, you can use the offset parameter. For example, suppose you have returned the first group of 250 orders using this call:
GET /ccadmin/v1/orders
You can return the next group of 250 using the following call:
GET /ccadmin/v1/orders?offset=250
The default value of offset is 0, which means the listing begins with the first item. So setting offset to 250 means the listing begins with the 251st item.
You can use limit and offset together. For example, to return the 401st through 600th order: 
GET /ccadmin/v1/orders?limit=200&offset=400

Control the Set of Properties Returned

Another way to reduce the size of responses is to return only certain properties. For example, products can have a large number of properties, but you may need only certain ones.

You can use the fields parameter to restrict the set of properties returned to only those you explicitly specify. The properties are specified as a comma-separated list. For example, to return only the id and displayName properties of products:
GET /ccadmin/v1/products?fields=items.id,items.displayName
Note that items is the key for the array of objects returned, so top-level properties are referred to as items.propertyName (for example, items.displayName). Properties of nested objects are specified using additional period delimiters. For example:
GET /ccadmin/v1/products?fields=items.listPrices.defaultPriceGroup
You can also use a special field, totalResults, to return the total number of items available (such as the total number of products in the catalog). For example:
GET /ccadmin/v1/products?fields=items.id,totalResults

Note that if a call does not use the fields parameter, totalResults is included in the response by default. For calls that use the fields parameter, totalResults is suppressed unless it is explicitly listed as one of the fields to include.

As an alternative to the fields parameter, which explicitly specifies the properties to include, you can use the exclude parameter to include all properties except the ones specified. For example, to return all of the properties of products except longDescription:

As with the fields parameter, properties of nested objects can be specified for the exclude parameter using additional period delimiters (for example, items.listPrices.defaultPriceGroup).

If you use both the fields and exclude query parameters in the same request, the fields parameter is applied first to determine the initial list of properties to return, and then the exclude parameter is applied to remove properties from that list.

You can also create persistent response filters that store a list of the properties to include and the properties to exclude. See Response filters.

Control the Order of Items Returned

By default, the items returned are sorted by a predetermined property that depends on the type of item. For example, products are sorted by displayName.

You can use the sort parameter to specify a different property to sort by. For example:
GET /ccadmin/v1/products?sort=id
You can append :asc or :desc to the property name to specify sorting in ascending or descending order. For example, to sort by id descending:
GET /ccadmin/v1/products?sort=id:desc
If you do not specify a sort order, it defaults to ascending.
You can specify multiple properties for sorting. The following call returns results sorted first by listPrice, and then by displayName (for items with identical listPrice values):
GET /ccadmin/v1/products?sort=listPrice,displayName

Note that sorting is done before applying limit and offset values, so it can affect not only the order in which items appear in the response, but also which items are returned. For example, if limit=200 and offset=400, items 401 to 600 are selected from the sorted list of all items. If you change the sorting criteria, items 401 to 600 may not be the same ones as before.

Filter Results

Many endpoints that return a list of items support the q query parameter. This parameter is used for specifying a filter expression that restricts the set of the items returned, based on criteria such as numeric comparisons or string matching with the values of the items’ properties. For example, the following call returns only those products whose orderLimit property has a value of less than 10:
GET /ccadmin/v1/products?q=orderLimit lt 10
For most endpoints that support it, the q parameter accepts filter expressions that use the syntax described in Section 3.2.2.2 of the System for Cross-Domain Identity Management (SCIM) specification, which is available at https://tools.ietf.org/html/draft-ietf-scim-api-12. A few endpoints accept filter expressions that use RQL syntax instead, as discussed below.

Use SCIM expressions for filtering

The SCIM specification defines standardized services for managing user identities in cloud environments. These services include a querying language for filtering the results returned by REST endpoints.

In SCIM filtering expressions, text, date, and time values must be enclosed in quotation marks, with date and time values using ISO-8601 format. (Numeric and boolean values should not be quoted.) For example, the following call returns products whose description property starts with pa:
GET /ccadmin/v1/products?q=description sw "pa"
The operators are case-insensitive, as are strings used for matching. So, for example, the following calls return identical results:
GET /ccadmin/v1/products?q=displayName co "shirt"
GET /ccadmin/v1/products?q=displayName CO "sHIrt"
Note that filter expressions must be URL encoded, so you must ensure that characters such as the quotation mark (") are escaped properly.
SCIM also supports the logical operators AND, OR, and NOT. For example, the following call returns products whose orderLimit property has a value between 5 and 10:
GET /ccadmin/v1/products?q=orderLimit gt 5 and orderLimit lt 10

Restrictions on filtering

Not all properties can be used in filter expressions. The following are some limitations you should be aware of:
  • You can use only top-level properties of items in filter expressions. For example, for product endpoints, you cannot include properties of subobjects such as child SKUs.
  • You can use a property in filter expressions only if it is returned by the endpoint you are calling. For example, if a specific product property is not returned by the GET /ccadmin/v1/products endpoint, then the property cannot be used with the q parameter for that endpoint. Note, however, that equivalent endpoints in different APIs (for example, GET /ccadmin/v1/products and GET /ccstore/v1/products) may not return identical sets of properties, so a property that is not returned by one of these endpoints may be returned by the other.

Also, if you have multiple custom product types, and two or more custom types have a custom property with the same name, the property cannot be used in filter expressions. For example, if you have two custom product types called Shoes and Hats, and each has a custom property called material, then you cannot use material in filter expressions. If only one custom product type has a material property, you can use the property in filter expressions.

Use RQL expressions for filtering

As mentioned above, a few endpoints use RQL syntax for filtering instead of SCIM syntax. These are:
GET /ccadmin/v1/exchangerates
GET /ccadmin/v1/orders
GET /ccadmin/v1/posts
GET /ccadmin/v1/serverExtensions
GET /ccadmin/v1/webhookFailedMessages
For example, this call uses RQL syntax for a numeric comparison:
GET /ccadmin/v1/exchangerates?q=exchangeRate > 3.5
This call uses RQL syntax for a timestamp comparison:
GET /ccadmin/v1/webhookFailedMessages?q=savedTime=datetime("2018-9-22 12:05:54 GMT")
Note that the endpoints that use RQL syntax by default can optionally use SCIM instead. To enable SCIM syntax for one of these endpoints, use the queryFormat query parameter. For example:
GET /ccadmin/v1/orders?queryFormat=SCIM&q=profileId eq "110658"