Query Parameters
Oracle Commerce REST APIs support a number of query parameters that you can use to control what data is returned in GET endpoint responses.
Controlling the set of items returned (limit and offset)
GET /ccadmin/v1/orders?limit=5
GET /ccadmin/v1/orders
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.
GET /ccadmin/v1/orders?limit=200&offset=400
Controlling the set of properties returned (fields and exclude)
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.
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
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
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.
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
:
GET /ccadmin/v1/products?exclude=items.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
).
Controlling the order of items returned (sort)
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
.
GET /ccadmin/v1/products?sort=id
: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.
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.
Filtering results (q)
You can use the q
query parameter to specify a filter expression for restricting the set of the items returned, based on criteria such as numeric comparisons or string matching with the values of the item's properties. The q parameter accepts filter expressions in the format 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
.
orderLimit
property has a value of less than 10:
GET /ccadmin/v1/products?q=orderLimit lt 10
GET /ccadmin/v1/products?q=description sw "pa"
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.
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
-
You can use only top-level properties of products in filter expressions. 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 theq
parameter for that endpoint. Note, however, that theGET /ccadmin/v1/products
andGET /ccstore/v1/products
endpoints do not return identical sets of properties, so a property that is not returned by one of these endpoints may be returned by the other.
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.
q
parameter by default 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
queryFormat
query parameter. For example:
GET /ccadmin/v1/orders?queryFormat=SCIM&q=profileId eq "110658"
Response filters
fields
and
exclude
query parameters. Rather than using
fields
or
exclude
to explicitly list properties in the URL of a REST call, you can create persistent filters that store the set of properties to include or exclude. You can then specify a filter by name in the URL using the
filterKey
query parameter. For example, you could create a response filter named
productSummary
that lists product properties to include, and then invoke the filter like this:
GET /ccadmin/v1/products?filterKey=productSummary
A response filter is essentially a wrapper for the fields
and exclude
query parameters. Each filter must have a key
(which is used to identify the filter), and either an include
array (equivalent to the fields
query parameter) an exclude
array (equivalent to the exclude
query parameter), or both. The properties returned by a filter are the same as they would be for equivalent fields
and exclude
expressions. If you include the filterKey
query parameter and either fields
or exclude
(or both) in an API call, filterKey
is ignored, and fields
and exclude
are applied.
By default there are several response filters included with Commerce. To view a list of response filters, use the listFilters
endpoint in the Admin API. You should not modify or delete the default response filters, as they are used by widgets provided with Commerce. You can create your own response filters using the createFilter
endpoint.