Applies to: Catalog API
Learn how to search for items or item variations using one or more supported query filters.
The SearchCatalogItems endpoint can take one or more of the following query filters:
- The category_token filter returns catalog items or item variations of specified category IDs.
- The custom_attribute_filters query expressions return items or item variations of the specified custom attributes.
- The does_not_exist filter returns items or item variations containing the following nullable attributes.
- The enabled_unit_tokens filter returns items or item variations with the specified enabled units.
- The product_types filter returns items or item variations of the specified product types.
- The stock_level filter returns items or item variations of the specified stock level.
- The text_filter query returns items or item variations containing the specified text terms in searchable attributes.
- The CustomAttributeFilter returns items or item variations matching specified custom attributes.
When you use more than one filter, the returned result contains items and item variations that satisfy all the query conditions.
Search with category tokens means to query catalog items of given categories as identified by the specified category IDs.
The following cURL example searches for items by matching the items' category_id attribute against the specified category_token filter expressed as a list of category IDs:
Search catalog items
The successful response looks similar to the following result:
{
"items": [
{
"type": "ITEM",
"id": "3ZDFHLLYFEE2SUUI65MVBK73",
"updated_at": "2020-06-23T18:03:31.656Z",
"version": 1592935411656,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Item of Category One",
"description": "Item of category 1",
"abbreviation": "itm_c1",
"available_for_pickup": true,
"available_electronically": true,
"category_id": "GCCTVZOTCOPI246SREKXNMYX",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "A6QZQQSLDZPV3TM7TQIKEIXZ",
"updated_at": "2020-06-23T18:03:31.656Z",
"version": 1592935411656,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "3ZDFHLLYFEE2SUUI65MVBK73",
"name": "Item variations of category",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 100,
"currency": "USD"
},
"inventory_alert_type": "LOW_QUANTITY",
"inventory_alert_threshold": 10
}
}
],
"product_type": "REGULAR"
}
}
],
"matched_variation_tokens": [
"A6QZQQSLDZPV3TM7TQIKEIXZ"
]
}You can search for items or item variations using text_filter to match specified string tokens against searchable attribute values of items or item variations. Searchable attributes include name, description, and others.
Search by text is a form of free-text search in which the query expression is tokenized into a list of tokens. Matching is conducted by comparing tokenized searchable attribute values of items or item variations token by token, irrespective of the token orders, against the tokenized query expression.
The following example fetches items or item variation containing the Coffee and Drink tokens:
Search catalog items
The successful response returns the result similar to the following, if the catalog has one. Otherwise, the result is an empty set.
{
"items": [
{
"type": "ITEM",
"id": "QRIAAXI7PEBG6WDEX6DG6WHL",
"updated_at": "2020-05-29T22:25:47.216Z",
"version": 1590791147216,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Coffee",
"description": "Coffee Drink",
"abbreviation": "Co",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "LBHSVD65G6MXCNYV2AP2TYPP",
"updated_at": "2020-05-29T20:38:28.304Z",
"version": 1590784708304,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "QRIAAXI7PEBG6WDEX6DG6WHL",
"name": "Small",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 300,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "AH2XNLUYOV4RCVBSJX66F7RV",
"updated_at": "2020-05-29T20:58:34.455Z",
"version": 1590785914455,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "QRIAAXI7PEBG6WDEX6DG6WHL",
"name": "Large",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 350,
"currency": "USD"
}
}
}
],
"product_type": "REGULAR"
}
}
],
"matched_variation_tokens": [
"AH2XNLUYOV4RCVBSJX66F7RV",
"LBHSVD65G6MXCNYV2AP2TYPP"
]
}Because matching is independent of the token orders, you get the same result if you use the following text_filter:
{ "text_filter": "Drink Coffee" }
Furthermore, a token in the query can match part of a token in an attribute of an item or item variation. Hence, the following variation of the previous text_filter returns the same results as previously shown:
{ "text_filter": "Coff Drin" }
You can combine a text search with specific product types when calling the SearchCatalogItems endpoint. You get the result that matches all the query expressions.
The following example searches for items and item variations by a specified product type that also contains Coffee in their searchable attribute values.
Search catalog items
The successful response returns a result similar to the following:
{
"items": [
{
"type": "ITEM",
"id": "QRIAAXI7PEBG6WDEX6DG6WHL",
"updated_at": "2020-05-29T22:25:47.216Z",
"version": 1590791147216,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Coffee",
"description": "Coffee Drink",
"abbreviation": "Co",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "LBHSVD65G6MXCNYV2AP2TYPP",
"updated_at": "2020-05-29T20:38:28.304Z",
"version": 1590784708304,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "QRIAAXI7PEBG6WDEX6DG6WHL",
"name": "Small",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 300,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "AH2XNLUYOV4RCVBSJX66F7RV",
"updated_at": "2020-05-29T20:58:34.455Z",
"version": 1590785914455,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "QRIAAXI7PEBG6WDEX6DG6WHL",
"name": "Large",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 350,
"currency": "USD"
}
}
}
],
"product_type": "REGULAR"
}
}
],
"matched_variation_tokens": [
"AH2XNLUYOV4RCVBSJX66F7RV",
"LBHSVD65G6MXCNYV2AP2TYPP"
]
}If your catalog doesn't contain any items satisfying the both query expressions, you receive an empty payload in a 200 OK response.
When items or item variations have custom attribute values assigned to them, you can call the SearchCatalogItems endpoint to search for them by their custom attribute values. To do so, you supply a list of custom_attribute_filter query expressions, expressed as JSON objects. If a custom attribute value contains the key value of cocoa_brand, the custom_attribute_filter can be expressed as {"key": "cocoa_brand"}.
The following cURL example shows how to call the SearchCatalogItems endpoint to search for items with a custom attribute filter:
Search catalog items
On the other hand, if you know the custom attribute definition ID ("NPQJUZVDBE6EKZ25EU3GPLC5") of the custom attribute value, you can express the custom_attribute_query filters as follows:
{ "custom_attribute_filters": [ { "custom_attribute_definition_token": "NPQJUZVDBE6EKZ25EU3GPLC5" } ] }
If the custom attribute value has the string_value property assigned the "Cocoa Magic" value, you can call the SearchCatalogItems endpoint with the following custom_attribute_filters:
"custom_attribute_filters": [ { "string_filter": "Cocoa Magic" } ]
If such items are present in the catalog and the request succeeds, you get the result in a response similar to the following:
{
"items": [
{
"type": "ITEM",
"id": "GPOKJPTV2KDLVKCADJ7I77EZ",
"updated_at": "2020-06-18T17:55:56.646Z",
"version": 1592502956646,
"is_deleted": false,
"custom_attribute_values": {
"cocoa_brand": {
"name": "Brand",
"string_value": "Cocoa Magic",
"custom_attribute_definition_id": "NPQJUZVDBE6EKZ25EU3GPLC5",
"type": "STRING",
"key": "cocoa_brand"
}
},
"present_at_all_locations": true,
"item_data": {
"name": "Hot Cocoa",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "VBJNPHCOKDFECR6VU25WRJUD",
"updated_at": "2020-06-18T17:55:56.646Z",
"version": 1592502956646,
"is_deleted": false,
"custom_attribute_values": {
"topping": {
"name": "Tasting Notes",
"custom_attribute_definition_id": "EI7IJQDUKYSHULREPIPH6HNU",
"type": "SELECTION",
"selection_uid_values": [
"VF4QVHAT63I6KO356BDDHNC3",
"A54CJAXS32EUXINOTUPRXQAL"
],
"key": "topping"
}
},
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "GPOKJPTV2KDLVKCADJ7I77EZ",
"name": "Small",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 500,
"currency": "USD"
}
}
}
],
"product_type": "REGULAR"
}
}
],
"matched_variation_tokens": [
"VBJNPHCOKDFECR6VU25WRJUD"
]
}If the items or item variations in your catalog have different custom attribute values of the same key, you can narrow the scope of the search result by adding other query conditions. For example, you can append a string_filter expression to the key expression in a custom_attribute_filter when calling the SearchCatalogItems, as shown the following example. This lets you search for items or items variations with custom attribute values having the key of cocoa_brand and the string_value containing Cocoa Magic.
"custom_attribute_filters": [ { "key": "cocoa_brand", "string_filter": "Cocoa Magic" } ]
However, when you use a selection_tokens_filter, the returned search results are items or item variations matching any of the specified selection tokens against the selection_uid_values of their custom_attribute_values.
You can specify multiple query conditions in a single query filter to narrow the scope of the search target or to make the search more selective.
You can also assign multiple query filters to the custom_attribute_filters input property, as shown:
"custom_attribute_filters": [ { "custom_attribute_definition_token": "NPQJUZVDBE6EKZ25EU3GPLC5" }, { "key": "cocoa_brand" } ]
The result contains items each of which has a custom_attribute_value property matching all the query conditions in all the query filters. Because an item or item variation can have multiple custom attribute values, using multiple custom attribute filters helps make the search more selective to narrow the scope of the search result.