Sorting and Filtering
The Kibo eCommerce API exposes various operations that can retrieve large item collections. For example, you could conceivably use a GetProducts request to return every product in a given catalog. Of course, such a large data set would be difficult to manage. Sorting and filtering can narrow the returned data to more usable chunks.
Note: Operations that support sorting and filtering include sortBy and filter in their list of parameters.Sorting
Sort Operators
| Operator | Symbol | Sample Request |
|---|---|---|
| Ascending | asc | /?sortBy=id asc |
| Descending | desc | /?sortBy=createDate desc |
You can sort by as many parameters as you want. Simply use a comma to separate sort parameters.
Sort Examples
| Example | Query String |
|---|---|
| Sort the result of a GetOrders operation by the date the order was accepted, then by the unpaid balance on the order. |
GET
api/commerce/orders/?sortBy=order.acceptedDate+asc,order.amountRemainingForPayment+desc |
Special Case: Dynamic Attribute Value Sorting on ProductVariations
Note: The product variations service has a special exception/ability that other services do not support. This exception/ability is a parametrized sort.The property Attribute Value Internal in the ProductVariations allows sorting by the Attribute Id. Unlike other services/locations, Attribute Value Internal is a dynamically calculated value for ProductVariations.
| Example | Query String |
|---|---|
| Sort by attribute Id in ascending order | /?sortBy=attributevalueinternal:123 asc |
| Sort by attribute Id in descending order | /?sortBy=attributevalueinternal:123 desc |
Filtering
Filter Operators
| Operator | Symbol | Sample Request |
|---|---|---|
| Equals | eq | /?filter=id eq 2 |
| Not Equals | ne | /?filter=createBy ne Dave |
| Greater Than | gt | /?filter=discountTotal gt 50 |
| Less Than | lt | /?filter=submittedDate lt 2015-01-01T12:00:00z |
| Greater Than Or Equal To | ge | /?filter=createdDate ge 2015-01-01T12:00:00z |
| Less Than Or Equal To | le | /?filter=taxTotal le 10 |
| And | and | /?filter=size eq 11 and product.productPrice.catalogListPrice eq 100 |
| Or | or | /?filter=size eq 11 or size eq 11.5 |
| Start Group/End Group | ( ) | /?filter=(size eq 11 or name sw shoe) or (size eq 13) |
| Starts With | sw | /?filter=name sw bro |
| Contains | cont | /?filter=name cont nike |
| In | in[N...N+1] | /?filter=property in[1,2,3] |
| Between | between[N1,N2] | /?filter=property between[0,100] |
Special Characters and Filters
If your filter value contains any special characters, you must escape the special characters for the filtering funtionality to properly work.
Refer to the following list for the special characters that you must escape:
- ^
- \
- "
- ' (single quote)
- , (comma)
- {
- }
- (
- )
Escape Special Characters
To escape special characters, use a caret character (^) before any special characters.
For example, you want to use the filter filter=content.productName+cont+women^'s on a GetProducts call. Note the use of the caret before the apostrophe s in women's (women^'s).
Filter Examples
Note: In most cases, the filter for a field is simply the name of that field. For some exceptionally long field names, Kibo eCommerce allows shortened filter values. Refer to the specific resource tables at the end of this topic for examples of valid filter strings for each filterable field.| Example | Query String |
|---|---|
| Where the Id is equal to 2. | /?filter=id eq 2 |
| Where the name property of the discount sub-entity content contains the text "test" | /?filter=discount.content.name cont test |
| Where size is equal to 12 or 13 and name is equal to “brand name shoes” (case insensitive) and escaping spaces with double quotes. | /?filter=(size eq 12 or size eq 13) and (name eq ”brand name shoes”) |
| Where size is equal to 12 or 13 and name is equal to “brand name shoes” (case insensitive) and escaping spaces with single quotes. | /?filter=(size eq 12 or size eq 13) and (name eq 'brand name shoes') |
| Where size is equal to 11 or name starts with “shoe” or size is equal to 13 | /?filter=(size eq 11 or name sw shoe) or (size eq 13) |
| Where size is equal to 11 or name starts with “shoe” or size is equal to 13 using a single quote literal (double quotes are also supported) | /?filter=(size eq 11 or name sw 'shoe') or (size eq 13) |
Combined Filter and Sort Examples
At times, you might want to both filter your data and then sort the items that fit the filter requirements.
| Example | Query String |
|---|---|
| Where the name property of the discount sub-entity content contains the text "test" and sort the results by “discount.content.name” ascending then by “CreateDate” descending | /?filter=discount.content.name cont test&sortBy=discount.content.name asc,createdate desc |
Filters by Resource
Customer Account Filters
When searching for a collection of customer accounts using the filter parameter in the request URL, you can use any of the following supported filter, operator, and value combinations to refine the search results.
Corresponding Resource: commerce/customer/accounts
| Field | Description and Examples | Supported Filters | Possible Values | Sort By? |
|---|---|---|---|---|
| acceptsMarketing |
Indicates if the customer account is set to receive marketing materials. /?filter=acceptsmarketing+eq+true /?sortby=acceptsmarketing+asc |
Equals (eq) | A Boolean value, specified as true or false. | Yes |
| attributes.id |
A unique identifier used to identify an attribute on the customer account. /?filter=attributes.id+cont+gmail |
Equals (eq) Does Not Equal (ne) Less Than (lt) Less Than or Equal To (le) Greater Than (gt) Greater Than or Equal To (ge) |
Any integer. | No |
| attributes.name |
The name of an attribute on the customer account. /?filter=attributes.name+cont+gmail |
Equals (eq) Does Not Equal (ne) |
Depend on the data type of the attribute. Supported types are string, date/time, decimal, and Boolean. | No |
| attributes.value |
The value of an attribute on the customer account. /?filter=attributes.value+cont+gmail |
Equals (eq) Does Not Equal (ne) |
Depend on the data type of the attribute. Supported types are string, date/time, decimal, and Boolean. | No |
| companyOrOrganization |
The company or organization name associated with the customer account. /?filter=companyororganization+eq+mozu /?sortby=companyororganization+desc |
Equals (eq) | Any alphanumeric string. | Yes |
| commerceSummary.lastOrderDate |
The date of the last order made on the account. /?filter=commercesummary.lastorderdate+gt+2016-04-15T08:00:00.000Z /?sortby=commercesummary.lastorderdate+desc |
Equals (eq) Less Than (lt) Less Than or Equal To (le) Greater Than (gt) Greater Than or Equal To (ge) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
| commerceSummary.orderCount |
The total number of orders in the customer account history. /?filter=commercesummary.ordercount+gt+10 /?sortby=commercesummary.ordercount+desc |
Equals (eq) Less Than (lt) Less Than or Equal To (le) Greater Than (gt) Greater Than or Equal To (ge) |
Any integer. | Yes |
| commerceSummary.totalOrderAmount |
The total monetary amount of all orders on the customer account, including cancellations and refunds. /?filter=commercesummary.totalorderamount+gt+10000 /?sortby=commercesummary.totalorderamount+asc |
Equals (eq) Less Than (lt) Less Than or Equal To (le) Greater Than (gt) Greater Than or Equal To (ge) |
Any integer. | Yes |
| commerceSummary.wishlistCount |
The total number of wishlists in the customer account. /?filter=commercesummary.wishlistcount+gt+10 /?sortby=commercesummary.wishlistcount+desc |
Equals (eq) Less Than (lt) Less Than or Equal To (le) Greater Than (gt) Greater Than or Equal To (ge) |
Any integer. | Yes |
| contacts.firstName |
The first name associated with a contact in the customer account. /?filter=contacts.firstname+sw+a |
Contains (cont) Equals (eq) Starts With (sw) |
Any alphanumeric string. | No |
| contacts.lastNameOrSurname |
The last name associated with a contact in the customer account. /?filter=contacts.lastnameorsurname+eq+smith |
Contains (cont) Equals (eq) Starts With (sw) |
Any alphanumeric string. | No |
| contacts.email |
The email associated with a contact in the customer account. /?filter=contacts.email+cont+gmail |
Contains (cont) Equals (eq) Starts With (sw) |
Any alphanumeric string. | No |
| createDate |
The date the customer account was created. /?sortby=createdate+asc /?filter=createdate+eq+2016-04-26T00:00:00.0000000Z (matches accounts created on April 16, 2016—the exact time doesn't matter) |
Equals (eq) Less Than (lt) Less Than or Equal To (le) Greater Than (gt) Greater Than or Equal To (ge) |
A date/time in UTC format. | Yes |
| customerSet |
The details of the customer set. /?filter=attributes.customerset+cont+gmail |
Equals (eq) Does Not Equal (ne) |
Any alphanumeric string. | No |
| emailAddress |
The email address for the customer account. /?filter=emailaddress+cont+mozu |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| externalId |
A unique identifier used by an external program to identify the customer account. /?filter=externalid+eq+abc123 /?sortby=externalid+asc |
Equals (eq) Starts With (sw) Contains (cont) |
Any alphanumeric string. | Yes |
| firstName |
The first name on the customer account. /?filter=firstname+sw+d |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| lastName |
The last name on the customer account. /?filter=lastname+eq+smith |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| segments.id |
The unique identifier of a customer segment that includes the account. /?filter=segments.id+eq+1 |
Equals (eq) Does Not Equal (ne) |
Any integer. | No |
| segments.code |
The user-defined code that uniquely identifies a segment that includes the account. /?filter=segments.code+eq+vip |
Equals (eq) Does Not Equal (ne) |
Any alphanumeric string. | No |
| segments.name |
The user-defined name that appears in Admin for a segment that includes the account. /?filter=segments.name+eq+gold |
Equals (eq) Does Not Equal (ne) Starts With (sw) Contains (cont) |
Any alphanumeric string. | No |
| tag |
The tag associated with the account. /?filter=tag+eq+x |
Equals (eq) | Any alphanumeric string. | No |
| updateDate |
The date the customer account was last updated. /?filter=updatedate+lt+2016-04-26T22:00:00.0000000Z (matches accounts updated before April 26, 2016 10:00PM UTC (5:00PM CDT)) |
Equals (eq) Less Than (lt) Less Than or Equal To (le) Greater Than (gt) Greater Than or Equal To (ge) |
A date/time in UTC format. | No |
| userId |
The unique identifier of the user. This field only appears if the account has an associated user ID. /?filter=userid+eq+tester /?sortby=userid+desc |
Equals (eq) Does Not Equal (ne) |
Any alphanumeric string (max length 55 characters). | Yes |
| userName |
The user name associated with the user profile. /?filter=username+eq+tester /?sortby=username+desc |
Equals (eq) Does Not Equal (ne) |
Any alphanumeric string (max length 55 characters). | No |
Locations Filters
When searching for a collection of locations using the filter parameter in the request URL, you can use any of the following supported filter, operator, and value combinations to refine the search results.
Corresponding Resource: commerce/admin/locations
| Field | Description and Examples | Supported Filters | Possible Values | Sort By? |
|---|---|---|---|---|
| code |
The user-defined code of the location. /?filter=code+eq+20 /?sortby=code+asc |
Equals (eq) | Any valid location code. | Yes |
| countryCode |
The country code associated with the location address. /?filter=countryCode+eq+US |
Equals (eq) | Any valid two-letter ISO country code. | No |
| fulfillmentType.Code |
The user-defined code that identifies the fulfillment type. /?filter=fulfillmenttype.code+eq+ds |
Equals (eq) Does Not Equal (ne) |
Any valid location type code. | No |
| geo |
The geographical location to use as a basis for the search, which consists of a latitude value, a longitude value, and the maximum distance (in meters) to search for locations. /?filter=geo+near(0.123,55.321,10000) |
Near (near) | Comma-separated geographical coordinates and distance value in meters. | No |
| isDisabled |
Indicates whether the location is disabled. /?filter=isdisabled+eq+true |
Equals (eq) Does Not Equal (ne) |
A Boolean value, specified as true or false. | No |
| locationType.Code |
The user-defined code that identifies the location type. /?filter=locationType.Code+eq+Warehouse |
Equals (eq) Does Not Equal (ne) |
Any valid location type code. | No |
| name |
The user-defined name of the location. /?filter=name+cont+airport /?sortby=name+desc |
Contains (cont) Starts With (sw) |
Any alphanumeric string. | Yes |
| postalOrZipCode |
The postal or zip code associated with the location address. /?filter=postalOrZipCode+eq+78745 |
Equals (eq) | Any valid zip or postal code. | No |
| state |
The state or province associated with the location address. /?filter=state+eq+TX |
Equals (eq) | Any valid state code. | No |
| supportsInventory |
Whether the location supports an active product inventory. /?filter=supportsInventory+eq+true /?sortby=supportsInventory+asc |
Equals (eq) Does Not Equal (ne) |
A Boolean value, specified as true or false. | Yes |
Location Inventory Filters
When searching for a collection of product definitions in the Location Inventory resource using the filter parameter, you can use any of the following supported filter, operator, and value combinations to refine the search results.
Corresponding Resources: commerce/catalog/admin/locationinventory, commerce/catalog/admin/products/LocationInventory
| Field | Description and Examples | Supported Filters | Possible Values | Sort By? |
|---|---|---|---|---|
| baseProductCode |
The unique, user-defined code for the base product. This is the prefix off which variation codes are generated. /?filter=baseProductCode+eq+MH0001 |
Equals (eq) |
Any alphanumeric string. |
No |
| createBy |
Identifier of the user that created the object. /?filter=createby+eq+smith |
Equals (eq) | Any alphanumeric string. | No |
| createDate |
The date the location inventory object was created. /?filter=createdate+gt+2016-04-15T08:00:00.000Z /?sortby=createdate+asc |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
| locationCode |
The unique, user-defined code that identifies a location. /?filter=locationcode+sw+tx /?sortby=locationcode+desc |
Equals (eq) |
Any alphanumeric string. |
Yes |
| productCode |
The unique, user-defined code that identifies a product. /?filter=productcode+sw+mys /?sortby=productcode+asc |
Equals (eq) |
Any alphanumeric string. |
Yes |
| productName |
The name of a product. /?filter=productname+sw+deluxe |
Equals (eq) |
Any alphanumeric string. |
No |
| stockOnHand |
The quantity of the product currently available in inventory. /?filter=stockonhand+le+40 /?sortby=stockonhand+asc |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any integer. | Yes |
| stockAvailable |
The quantity of the product accounted for in inventory that are available for purchase. /?filter=stockavailable+ge+25 /?sortby=stockavailable+desc |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any integer. | Yes |
| stockOnBackOrder |
The stock level for the associated product currently on back order for this location, based on the number of pending product reservations. /?filter=stockonbackorder+le+1 /?sortby=stockonbackorder+desc |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any integer. | Yes |
| updateBy |
Identifier of the user that last updated the object. /?filter=updateby+eq+smith |
Equals (eq) | Any alphanumeric string. | No |
| updateDate |
The date the location inventory object was last updated. /?filter=updatedate+gt+2016-04-15T08:00:00.000Z /?sortby=updatedate+asc |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
Orders Filters
Query Behavior
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.
Supported Filters
When searching for a collection of orders using the filter parameter in the request URL, you can use any of the following supported filter, operator, and value combinations to refine the search results.
Corresponding Resource: commerce/orders
| Field | Description and Examples | Supported Filters | Possible Values | Sort By? |
|---|---|---|---|---|
| auditInfo.createBy |
The unique identifier of the user who created the order. /?filter=auditinfo.createby+cont+smith |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| auditInfo.updateBy |
The unique identifier of the user who last updated the order. /?filter=auditinfo.updateby+eq+smith |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| attributes.attributeDefinitionId |
The unique identifier of an attribute definition associated with the order. /?filter=attributes.attributedefinitionid+cont+smith OR /?filter=attributes.id+cont+smith |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any integer. | No |
| attributes.fullyQualifiedName |
The name of an attribute associated with the order. /?filter=attributes.name+cont+smith |
Contains (cont) Equals (eq) Does Not Equal (ne) |
Any string. | No |
| attributes.values |
The value of an attribute associated with the order. /?filter=attributes.value+cont+smith |
Equals (eq) Does Not Equal (ne) |
Depends on the data type of the attribute. | No |
| billingInfo.billingContact.address |
The billing address set for the order. /?filter=billinginfo.billingcontact.address+cont+tx |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| billingInfo.billingContact.address.cityOrTown |
The city or town associated with the billing address set for the order. /?filter=billinginfo.billingcontact.address.cityortown+eq+austin |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| billingInfo.billingContact.address.countryCode |
The country code associated with the billing address set for the order. /?filter=billinginfo.billingcontact.address.countrycode+eq+us |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any valid ISO country code. | No |
| billingInfo.billingContact.address.postalOrZipCode |
The zip code associated with the billing address set for the order. /?filter=billinginfo.billingcontact.address.postalorzipcode+sw+7 |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any valid ISO country code. | No |
| billingInfo.billingContact.address.stateOrProvince |
The state or province associated with the billing address set for the order. /?filter=billinginfo.billingcontact.address.stateorprovince+ne+texas |
Contains (cont) Equals (eq) Does Not Equal (ne) |
Any alphanumeric string. | No |
| billingInfo.billingContact.companyOrOrganization |
The company or organization associated with the billing information of the order. /?filter=billinginfo.billingcontact.companyororganization+eq+taxpro |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| billingInfo.billingContact.email |
The email address associated with the billing information of the order. /?filter=billinginfo.billingcontact.email+cont+gmail |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| billingInfo.billingContact.firstName |
The first name of the person associated with the billing information of the order. /?filter=billinginfo.billingcontact.firstname+cont+jo |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
| billingInfo.billingContact.lastNameOrSurname |
The last name or surname of the person associated with the billing information of the order. filter=billingInfo.billingContact.lastNameOrSurname+ne+jo |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
| billingInfo.billingContact.phonenumber |
The phone number associated to the billing address that the order was placed with. Note that this EQ filter actually performs an "ends with" comparison instead of an exact match. Thus, filtering for 15123334444, 3334444, or 4444 will all match with the phone number +1-512-333-4444. filter=billingInfo.billingContact.phonenumber+eq+5123334444 |
Equals (eq) | Any numeric string. | Yes |
| cardNumber |
The ending digits of the credit card used to place the order. /?filter=cardnumber+eq+4242 |
Contains (cont) Equals (eq) Does Not Equal (ne) In (in) Starts With (sw) |
Any number (should be a maximum of 4 digits). | Yes |
| cancelledDate |
The date and time the order was cancelled. /?filter=cancelleddate+lt+2015-08-098:52:00.959Z |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Less Than (lt) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
| channelCode |
The unique identifier of the channel in which the order was placed. /?filter=channelcode+sw+amer |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
| closedDate |
The date and time the order was closed. /?filter=closeddate+gt+2015-08-098:52:00.959Z |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Less Than (lt) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
| createBy |
The unique identifier of the user who created the order. /?filter=createby+cont+55 |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any valid user ID. | No |
| createDate |
The date and time the order was created. /?filter=createdate+ne+2015-08-098:52:00.959Z |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
| currencyCode |
The date and time the order was created. /?filter=currencycode+ne+USD |
Equals (eq) Does Not Equal (ne) |
Any valid ISO currency code. | No |
| customerAccountID |
The unique identifier of the customer account associated with the order. /?filter=customerAccountId+ne+81 |
Equals (eq) Does Not Equal (ne) |
Any valid customer account ID. | No |
| customerInteractionType |
The type of interaction the shopper used to create the order. /?filter=customerinteractiontype+sw+web |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Website Store Call Unknown |
Yes |
| discountTotal |
The amount of discounts applied to all items in an order. Usually a negative dollar amount or number. /?filter=discountTotal+le+20 |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any decimal. | No |
| dutyTotal |
The total amount of duties or tariffs applied to the order. /?filter=dutytotal+le+20 |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any decimal. | Yes |
|
The email address associated with the order. /?filter=email+cont+gmail |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No | |
| expirationDate |
The date and time the order is considered abandoned or no longer active. /?filter=expirationDate+gt+ 2015-08-098:52:00.959Z |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Less Than (lt) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | No |
| extendedProperties.key | Key used for metadata defined for objects. Typically used for tracking strings for orders. | Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| externalId |
The external ID of the order given to it by another source (such as the merchant or Borderfree, instead of the automatically-assigned eCommerce ID). /?filter=externalid+eq+12345 |
Contains (cont) Equals (eq) Does Not Equal (ne) In (in) Starts With (sw) |
Yes | |
| fulfillmentInfo.fulfillmentContact.address.cityOrTown |
The city or town associated with the fulfillment address set for the order. /?filter=fulfillmentinfo.fulfillmentcontact.address.cityortown+eq+austin |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| fulfillmentInfo.fulfillmentContact.address.countryCode |
The country code associated with the fulfillment address set for the order. /?filter=fulfillmentinfo.fulfillmentcontact.address.countrycode+ne+us |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any valid ISO country code. | No |
| fulfillmentInfo.fulfillmentContact.address.postalOrZipCode |
The postal code or zip code associated with the fulfillment address set for the order. /?filter=fulfillmentinfo.fulfillmentcontact.address.postalorzipcode+eq+78745 |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any integer. | No |
| fulfillmentInfo.fulfillmentContact.address.stateOrProvince |
The state or province associated with the fulfillment address set for the order. /?filter=fulfillmentinfo.fulfillmentcontact.address.stateorprovince+ne+texas |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| fulfillmentInfo.fulfillmentContact.companyOrOrganization |
The company or organization associated with the fulfillment information of the order. /?filter=fulfillmentinfo.fulfillmentcontact.companyororganization+sw+ta |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| fulfillmentInfo.fulfillmentContact.email |
The email address associated with the fulfillment information of the order. /?filter=fulfillmentinfo.fulfillmentcontact.email+cont+gmail |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| fulfillmentInfo.fulfillmentContact.firstName |
The first name of the person associated with the fulfillment information of the order. /?filter=fulfillmentinfo.fulfillmentcontact.firstname+eq+john |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
| fulfillmentInfo.fulfillmentContact.lastNameOrSurname |
The last name or surname of the person associated with the fulfillment information of the order. /?filter=fulfillmentinfo.fulfillmentcontact.lastnameorsurname+sw+jo |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
| fulfillmentInfo.fulfillmentContact.phonenumber |
The phone number associated to the shipping address that the order was placed with. Note that this EQ filter actually performs an "ends with" comparison instead of an exact match. Thus, filtering for 15123334444, 3334444, or 4444 will all match with the phone number +1-512-333-4444. /?filter=fulfillmentinfo.fulfillmentcontact.phonenumber+eq+5123334444 |
Equals (eq) | Any numeric string. | Yes |
| fulfillmentStatus |
The current shipment status of the order. /?filter=fulfillmentstatus+ne+fulfilled /?sortby=shipmentstatus+asc |
Contains (cont) Equals (eq) Does Not Equal (ne) In (in) Starts With (sw) |
Fulfilled NotFulfilled PartiallyFulfilled |
Yes |
| id |
The unique identifier of the order. This is a system-created GUID. /?filter=id+eq+02f87cdd14c6cc185c6434aa000012d1 |
Equals (eq) Does Not Equal (ne) |
Any valid order ID. | Yes |
| ipAddress |
The IP address from which the order originated. /?filter=ipAddress+eq+123.45.678.90 |
Equals (eq) Does Not Equal (ne) |
Any valid IP address. | No |
| items.fulfillmentLocationCode |
The code that identifies the location used to fulfill the order/order item. /?filter=items.fullfilmentlocationcode+sw+aus |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| items.fulfillmentMethod |
The method used to fulfill the order item. /?filter=items.fullfilmentmethod+sw+dig |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Ship Pickup Digital |
No |
| items.fulfillmentMethodAndLocationCode |
/?filter=items.fullfilmentmethodandlocationcode+eq+'pickup,Loc1' |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| items.mfgPartNumber |
The universal product code (UPC) defined for the order item. /?filter=items.mfgpartno+sw+dir |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| items.upc |
The universal product code (UPC) defined for the order item. /?filter=items.upc+sw+dir |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| lastValidationDate |
The date and time when the order was last validated against the product catalog. /?filter=lastValidationDate+lt+2015-08-098:52:00.959Z |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Less Than (lt) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
| orderNumber |
The merchant-defined order number. /?filter=ordernumber+lt+123456 |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any valid order number. | Yes |
| originalCartId |
The unique identifier of the cart from which the order was created. This is a system-created GUID. /?filter=originalCartId+ne+02f87b1a14c6cc185c6434a6000012d1 |
Equals (eq) Does Not Equal (ne) |
Any valid cart ID. | No |
| paymentStatus |
The current status of the order payment. /?filter=paymentStatus+eq+paid |
Contains (cont) Equals (eq) Does Not Equal (ne) In (in) Starts With (sw) |
Paid Pending Unpaid |
Yes |
| returnNumber |
The number of a return associated with an order. /?filter=returnNumber+eq+1 |
Equals (eq) | Any valid return number. | No |
| returnStatus |
The current status of all returns associated with the order. /?filter=returnStatus+eq+ReturnedInFull |
Equals (eq) | None InProgress Closed ReturnedInFull Note:The status values are different in Admin. Refer to Order Return Status for more information. |
No |
| shippingInfo.shippingContact.address.cityOrTown |
The city or town associated with the shipping address set for the order. /?filter=shippinginfo.shippingcontact.address.cityortown+eq+austin |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| shippingInfo.shippingContact.address.countryCode |
The country code associated with the shipping address set for the order. /?filter=shippingInfo.shippingContact.address.countryCode+ne+us |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any valid ISO country code. | No |
| shippingInfo.shippingContact.address.postalOrZipCode |
The postal code or zip code associated with the shipping address set for the order. /?filter=shippingInfo.shippingContact.address.postalOrZipCode+eq+78745 |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any integer. | No |
| shippingInfo.shippingContact.address.stateOrProvince |
The state or province associated with the shipping address set for the order. /?filter=shippinginfo.shippingcontact.address.stateorprovince+ne+texas |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| shippingInfo.shippingContact.companyOrOrganization |
The company or organization associated with the shipping information of the order. /?filter=shippinginfo.shippingcontact.companyororganization+sw+ta |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| shippingInfo.shippingContact.email |
The email address associated with the shipping information of the order. /?filter=shippinginfo.shippingcontact.email+cont+gmail |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | No |
| shippingInfo.shippingContact.firstName |
The first name of the person associated with the shipping information of the order. /?filter=shippinginfo.shippingcontact.firstname+eq+john |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
| shippingInfo.shippingContact.lastNameOrSurname |
The last name or surname of the person associated with the shipping information of the order. /?filter=shippinginfo.shippingcontact.lastnameorsurname+sw+jo |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
| siteId |
The unique identifier of the site from which the order was created. /?filter=siteid+eq+11111 |
Equals (eq) Does Not Equal (ne) |
Any valid site ID. | No |
| status |
The current state of the order. /?filter=status+sw+pro |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) In (in) |
Created Submitted PendingReview Validated Accepted Processing Completed Cancelled Abandoned |
Yes |
| submittedDate |
The date and time the order was submitted. /?filter=submittedDate+eq+ 2015-08-098:52:00.959Z |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Less Than (lt) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
| subtotal |
The amount of the order without sales tax, shipping costs, and other fees. /?filter=subtotal+lt+17.99 |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any decimal. | Yes |
| taxTotal |
The total amount of sales tax applied to the order. /?filter=taxTotal+ge+12.95 |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any decimal. | No |
| total |
The amount of the order, including items, sales tax, shipping costs, and other fees. /?filter=total+gt+179.24 /?sortby=total+asc |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any decimal. | Yes |
| type |
The type of the order, which can be Online or Offline. /?filter=type+eq+offline /?sortby=type+asc |
Contains (cont) Equals (eq) Does Not Equal (ne) In (in) Starts With (sw) |
Online Offline |
Yes |
| updateBy |
The unique identifier of the user who last modified the order. This is a system-created GUID. Note: This filter will match on any instance of updateBy in the order (Payment, Pickup, etc.)./?filter=updateBy+sw+a8 |
Contains (cont) Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any valid user ID. | No |
| updateDate |
The date and time the order was last modified. /?filter=updateDate+lt+2015-08-098:52:00.959Z |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. | Yes |
| userID |
The unique identifier of the user responsible for the order. /?filter=userId+eq+8a32c8c6959e407cb6bd1597e2a6d2cd |
Equals (eq) Does Not Equal (ne) |
Any valid user ID. | No |
| visitId |
The unique identifier of the visit that was active when the order was placed. /?filter=visitid+eq+8a32c8c6959e407cb6bd1597e2a6d2cd |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
| webSessionId |
The unique identifier of the web session used to place the order. /?filter=websessionid+eq+8a32c8c6959e407cb6bd1597e2a6d2cd |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. | Yes |
Product Attribute Filters
When searching for a collection of product attributes in the product admin service using the filter parameter in the request URL, you can use any of the following filter, operator, and value combinations to refine the search results.
Corresponding Resource: commerce/catalog/admin/attributedefinition/attributes
| Filter | Description and Example | Operators | Possible Values |
|---|---|---|---|
| attributeCode |
The merchant-defined code for the attribute. /?filter=attributeCode+cont+lace |
Contains (cont) Equals(eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. |
| adminName |
The administrator name associated with the attribute. /?filter=adminName+sw+l |
Contains (cont) Equals(eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. |
| namespace |
The namespace to which the attribute belongs. All attributes you create through Admin have a namespace of Tenant. Attributes that custom applications create through the Kibo eCommerce API might have a custom namespace. /?filter=namespace+eq+tenant |
Contains (cont) Equals(eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. |
| inputType |
The format in which the attribute is displayed to customers. /?filter=InputType+cont+text |
Contains (cont) Equals(eq) Does Not Equal (ne) Starts With (sw) |
YesNo Date DateTime List TextBox TextArea |
| valueType |
The value type of the attribute (predefined or user-defined). /?filter=ValueType+ne+predefined |
Contains (cont) Equals(eq) Does Not Equal (ne) Starts With (sw) |
Predefined |
| dataType |
The type of data the user must select or enter for the attribute. /?filter=DataType+eq+string |
Contains (cont) Equals(eq) Does Not Equal (ne) Starts With (sw) |
String Number Bool Product |
| content.name |
The name of the attribute as it appears to customers. /?filter=Content.Name+sw+la |
Contains (cont) Equals(eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. |
| createDate |
The date the attribute was created. /?filter=CreateDate+lt+2015-08-098:52:00.959Z |
Equals(eq) Does Not Equal (ne) Greater Than (gt) Less Than (lt) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. |
| updateDate |
The date the attribute was last updated. /?filter=UpdateDate+eq+2015-08-098:52:00.959Z |
Equals(eq) Does Not Equal (ne) Greater Than (gt) Less Than (lt) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. |
Product Definition Filters
When searching for a collection of product definitions in the Product Admin service using the filter parameter, you can use any of the following supported filter, operator, and value combinations to refine the search results.
Corresponding Resource: commerce/catalog/admin/products
| Filter | Description and Example | Operators | Possible Values |
|---|---|---|---|
| productCode |
The unique, user-defined code for the product, such as a SKU or item number. /?filter=ProductCode+cont+shoe |
Contains (cont) Equals (eq) Starts With (sw) |
Any alphanumeric string. |
| content.productName |
The name of the product. The productName represents a line item in a taxable order or product bundle. /?filter=Content.ProductName+cont+pump |
Contains (cont) Equals (eq) Starts With (sw) |
Any alphanumeric string. |
| categoryId |
Unique identifier of a product category associated with the product. /?filter=CategoryId+ne+1 |
Equals (eq) Does Not Equal (ne) |
Any integer. |
| productTypeId |
Unique identifier of the product type assigned for the product. /?filter=productTypeId+eq+3 |
Equals (eq) |
Any integer. |
| isValidForProductType |
Indicates whether the product is valid for its assigned product type. /?filter=isValidForProductType+eq+true |
Equals (eq) |
A Boolean value specified as true or false. |
| hasConfigurable Options |
Whether the product has options the customer can configure. /?filter=hasConfigurableOptions+eq+false |
Equals (eq) |
A Boolean value specified as true or false. |
| isVariation |
Whether the product in this request is a product variation of a product that has configurable options. /?filter=isVariation+eq+true |
Equals (eq) |
A Boolean value specified as true or false. |
| manageStock |
Whether to manage inventory for this product. /?filter=manageStock+eq+true |
Equals (eq) |
A Boolean value specified as true or false. |
| isRecurring |
Whether the product is purchased or fulfilled at a regular interval. /?filter=isRecurring+eq+true |
Equals (eq) |
A Boolean value specified as true or false. |
| isTaxable |
Whether the product is subject to the relevant sales tax. /?filter=IsTaxable+eq+true |
Equals (eq) |
A Boolean value specified as true or false. |
| price.price |
The price set for the product. /?filter=price.price+eq+199 |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any decimal. |
| productSequence |
The sequential order of the product. /?filter=productSequence+eq+1 |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any integer. |
| Sale Price |
The sale price set for the product. /?filter=price.salePrice+le+100 |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
Any decimal. |
| createDate |
The creation date and time for the product. /?filter=createDate+lt+2015-08-098:52:00.959Z |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. |
| updateDate |
The last modification date for the product. /?filter=updateDate+lt+2015-08-098:52:00.959Z |
Equals (eq) Greater Than (gt) Greater Than or Equal To (ge) Less Than (lt) Less Than or Equal To (le) |
A date/time in UTC format. You can specify just the date portion (YYYY-MM-DD) for gt or lt. |
| createBy |
The unique identifier of the user who created the product. This is a system-created GUID. /?filter=createBy+eq+30E9487F0C9743419063916457D96F6E |
Equals (eq) |
Any valid user ID. |
| updateBy |
The unique identifier of the user who last modified the product. This is a system-created GUID. /?filter=updateBy+eq+30E9487F0C9743419063916457D96F6E |
Equals (eq) |
Any valid user ID. |
Product Type Filters
When searching for a collection of product types in the product admin service using the filter parameter in the request URL, you can use any of the following filter, operator, and value combinations to refine the search results.
Corresponding Resource: commerce/catalog/admin/attributedefinition/producttypes
| Filter | Description and Example | Operators | Possible Values |
|---|---|---|---|
| name |
The name of the product type. /?filter=name+sw+sh |
Equals (eq) Does Not Equal (ne) Starts With (sw) |
Any alphanumeric string. |
| id |
The unique identifier for the product type. /?filter=id+eq+12 |
Equals (eq) Does Not Equal (ne) Greater Than (gt) Less Than (lt) |
Any integer. |
| isBaseProductType |
Indicates whether the product type is the base product type for the site group. There is only one BaseProductType per site group. /?filter=isBaseProductType+eq+true |
Equals (eq) Does Not Equal (ne) |
A Boolean value specified as true or false. |
Return Filters
When searching for a collection of returns in the commerce runtime service using the filter parameter in the request URL, you can use any of the following filter, operator, and value combinations to refine the search results.
Corresponding Resource: commerce/returns
| Filter | Description and Example | Operators | Possible Values | Sort By |
|---|---|---|---|---|
| id |
The unique identifier of the return. /?filter=id+eq+ecb684eeb0ae433d816aa61f00eef2ed |
Equals (eq) | Any valid return identifier. | No |
| returnNumber |
The number of a return associated with an order. /?filter=returnNumber+eq+1 |
Equals (eq) Does Not Equal (ne) |
Any valid return number. | No |
| status |
The status of a return associated with an order. /?filter=status+eq+Authorized |
Equals (eq) Does Not Equal (ne) |
Created Authorized Pending Received Restocked Shipped Refunded Closed Rejected Cancelled Refer to Return Status in the Returns guide topic for more information. |
No |