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: 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 and up to a maximum of 200 results to determine how many results are returned per page. The default value is 20.
- 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.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)
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: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
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
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.
Checkouts API Filters
The following API parameter and filter combinations are supported for checkout API filters (https://t{tenantId}-s{siteId}.{env}.mozu.com/api/commerce/checkouts ). Not all parameters are applicable to sorting based on ascending or descending order, so the sortable parameters are also noted in the table. The table describes all other filterable parameters for the Checkout APIs.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.