Sorting and Filtering APIs

Instead of making a GET call to retrieve a single object based on a known identifier, filters or combinations of filters can be used to create a search query instead. As a collection of results will be returned, sorting can also be applied to the query to organize the data in the response. 

The exact filtering method varies depending on the type of API. The Fulfillment APIs (shipments and packages) have very different syntax from the Non-Fulfillment APIs (customers, locations, returns, and orders), and the Non-Fulfillment APIs support specific parameters as the available filters. All of these syntax guidelines and value options are described in this guide under the appropriate section.

Sorting and Filtering Fulfillment APIs

The Shipments and Packages APIs support pagination, the ability to sort results in ascending or descending order based on the search term, and filtering by attributes. They use a different syntax than all other Kibo Composable Commerce Platform APIs (such as Order, Customer, Returns, etc.). 

The basic template for this syntax is:

.../?page={page}&pageSize={pageSize}&sort={field}&filter={filter}

The attributes that can be used to customize this query are listed below.

• page: Accepts a numeric value (starting from 0) indicating which page of results to begin on. There is no set maximum value - the number of available pages depends on how many total results are returned from the query.
• pageSize: Accepts a numeric value greater than 0 to determine how many results are returned per page. Though there is no maximum value, it is suggested to not return more than 200 results per page. The default value is 10.
• fields: Filtering API fields based on Squiggly syntax, such as ?fields=id,reporter[firstName]. See the Squiggly documentation for more information.
• sort: Use sort=field to arrange results in ascending order. Use sort=-field to arrange results in descending order.
• filter: Supports filtering by API parameters based on any of a number of logical operators. See below for the full list of operators and examples. While there is no limit to the number of filters that can be applied, it is Kibo's recommended best practice to use as few as possible. Using a large number of filters may result in a slow query.
• quickSearch: Accepts any alphanumeric value to search by external order ID, order number (exact match), shipment number (exact match), recipient name, first line of the receiving address, email address, item product code, or item name. There is no maximum length for this value.
• isLate: Accepts a true/false Boolean value. If true, it will query for shipments created at least one day ago.

Filter Operators

Filtering is based on comparisons and logical operators to find results relative to the API parameters being searched on. Note that a semicolon (;) can be used instead of AND, and a comma (,) can be used instead of OR.

Filtering Examples

This query searches for late shipments and filters the results based on a combination of the fulfillment location AND shipment status, to return the late shipments for a particular location.

.../shipments/?isLate=true&filter=fulfillmentLocationCode==Example_Location;shipmentStatus==READY

In this query, a regex filter is used to get shipments where the sender’s email address ends with “@kibocommerce.com”:

..../shipments/?filter=originContact.email=re=".*@kibocommerce.com"

Sorting and Filtering Non-Fulfillment APIs

All other APIs (such as Customer, Returns, Orders, Products, and so forth) all use the same syntax for filtering and sorting. However, the exact parameters that may be filtered on vary based on the API. 

The general sorting and filtering syntax and operators are defined below, followed by individual lists of filterable parameters by API.

Sorting

Sorting is achieved by using the sortBy field and setting it to an API parameter followed by either ascending or descending.

• asc: Sort in ascending order based on a given parameter (e.g. …/?sortBy=id+asc)
• desc: Sort in descending order based on a given parameter (e.g. …/?sortBy=createDate+desc)

If you omit the direction symbol, the default sort direction is "ascending."

You can sort by as many parameters as you want. Sort multiple parameters by using a comma to separate the parameters and ascending/descending preferences:

.../api/commerce/orders/?sortBy=order.acceptedDate+asc,order.amountRemainingForPayment+desc

Filtering

The full list of logical operators for filtering is:

Note that any special characters in the filters must be escaped by inserting a caret before the character in order for the filter to work (for example, filter=content.productName+cont+women^’s). These special characters are ^ / “ ‘ , { } ( )

Filtering Examples

The following query retrieves orders that were created on or after January 1st, 2020 and have a discount total of more than $50:

 .../api/commerce/orders/?filter=createdDate+ge+2015-01-01T12:00:00z+and+discountTotal+gt+50

The group filter is used to configure multiple logic operators and parameter combinations, such as querying for a specific shoe size and name OR alternatively, only a different size:

.../api/commerce/orders/?filter=(size+eq+11+or+name+sw+shoe)+or+(size eq 13)

The “in” operator searches for results that include any of the given set of values. (In contrast, the “between” operators only accepts two numeric operators as the beginning and end of the chronological set.) To retrieve orders with a property value of 1, 2, or 3:

> .../api/commerce/orders/?filter=property+in[1,2,3]

Regardless of what filtering is applied, sortBy can always be added to sort the results.

.../api/commerce/orders/?filter=discount.content.name+cont+test&sortBy=discount.content.name+asc,createdate+desc

Customer Accounts API Filters

The following API parameter and filter combinations are supported for searching customer accounts (.../commerce/customer/accounts). Not all fields are applicable to sorting based on ascending or descending order, so the sortable parameters are also noted in the table.

Filtering Examples

commerce/customer/accounts?pageSize=20&filter=segments.id ne 1 and attributes.id eq 4

Locations API Filters

The following API parameter and filter combinations are supported for searching locations. Not all fields are applicable to sorting based on ascending or descending order, so the sortable parameters are also noted in the table.

Orders API Filters

When searching for a collection of orders using the q parameter in the request URL, you can enter a search term that will search across the following fields:

• Order number
• Shopper name, email, or company

When you perform a keyword search for orders based on the shopper information, the system searches for orders with the shopper name defined in the order billing information. If a different shopper's name appears in the billing information, the system will not return the order in the search results.

As the Orders API supports more filters than the others listed above, the filters will be provided in two tables. The first table describes the contact parameters that are supported for filtering. These all apply to billingInfo.billingContact, fulfillmentInfo.fulfillmentContact, and shippingInfo.shippingContact. When using any of these filters, prepend one of those three contact types to the parameter name to specify the data being referenced. For instance, a billing contact’s name and a fulfillment contact’s name are differentiated in the following query:

…/?filter=billingInfo.billingContact+eq+NAME+and+fulfillmentInfo.fulfillmentContact.name+eq+NAME

Note that filtering by phone number will not necessarily look for an exact match, but will instead look for results that end with the filtered value. For example, if you have the phone number 1-512-333-4444, then searching for 15123334444, 5123334444, or 3334444 will all return that phone number.

The second table describes all other filterable parameters for the Orders API.

*These parameters correspond to the parameter of the same name under the product object of the item data block. In other words, filtering on items.mfgPartNumber will be interpreted as a filter referencing items.product.mfgPartNumber.

Product Attributes API Filters

The following API parameter and filter combinations are supported for searching product attributes (.../commerce/catalog/admin/attributeDefinition/attributes). Not all fields are applicable to sorting based on ascending or descending order, so the sortable parameters are also noted in the table.

Products API Filters

The following API parameter and filter combinations are supported for searching products (commerce/catalog/admin/products).

If filtering on a custom attribute name, you must specify the Fully Qualified Name (FQN) of the attribute. For example, if there is a custom attribute called "color" then use the filter "tenant~color eq Red" to retrieve only the Red products.

Product Storefront Location Filter

Additionally, you can filter the storefront Product Search API by locations.

Product Type API Filters

The following API parameter and filter combinations are supported for searching product types (commerce/catalog/admin/attributedefinition/producttypes.

Returns API Filters

The following API parameter and filter combinations are supported for searching returns. Not all fields are applicable to sorting based on ascending or descending order, so the sortable parameters are also noted in the table.

Subscription API Filters

The following API parameter and filter combinations are supported for searching subscription. Not all fields are applicable to sorting based on ascending or descending order, so the sortable parameters are also noted in the table.