Applies to: Catalog API
Learn how to programmatically search for objects of any type.
You can call the SearchCatalogObjects endpoint to search for catalog objects of any type using the following query filters assigned as a query parameter value:
- An
exact_queryfilter of the CatalogQueryExact type returns any types of objects matching a specified attribute name and value exactly. - A
prefix_queryfilter of the CatalogQueryPrefix type returns any types of objects matching a specified prefix of a given attribute value. - A
range_queryfilter of the CatalogQueryRange type returns any types of objects matching a specified numerical range of a given attribute value. - A
text_queryfilter of the CatalogQueryText type returns any types of objects matching specified keywords against searchable attribute values. Searchable attributes includenameanddescription. - A
sorted_attribute_queryexpression of the CatalogQuerySortedAttribute type sorts returned results in a specified order by a specified attribute. - An
items_for_tax_queryfilter of the CatalogQueryItemsForTax type returns items with specified tax payer IDs. - An
items_for_modifier_list_queryfilter of the CatalogQueryItemsForModifierList type returns items enabled with specified modifier lists as identified by their IDs. - An
items_for_item_optionsfilter of the CatalogQueryItemsForItemOptions type returns items with specified item options as identified by their IDs. - An
items_variations_for_item_option_values_queryfilter of the CatalogQueryItemVariationsForItemOptionValues type returns item variations with specified item option values as identified by their IDs.
In addition, you can call the SearchCatalogObjects endpoint to search for catalog objects by matching values of the following system attributes:
- A
begin_timeattribute returns objects last modified since the specified time. - An
include_deleted_objectsattribute of a Boolean value returns objects that include deleted objects (true) or not (false) matching other specified query filters. - An
include_related_objectsattribute of a Boolean flag returns (true) or not (false) objects related to those matching other specified query filters. - An
object_typesattribute returns objects of the specified types matching other specified query filters.
Unlike with the SearchCatalogItems endpoint, you cannot call SearchCatalogObjects while using any custom attribute query filters.
To search for catalog objects of a known attribute name and value, call the SearchCatalogObjects endpoint while supplying the exact_query filter in the query parameter.
This is illustrated in the following cURL examples.
The following cURL example searches for catalog objects with the name attribute having a value of coffee:
Search catalog objects
With the exact query filter, attribute names of objects are matched against the specified attribute name exactly. However, matching the values of objects against the specified attribute value isn't case-sensitive.
The successful response returns the result similar to the following, if queried objects are found. Otherwise, the response payload is an empty JSON object.
{
"objects": [
{
"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",
"modifier_list_info": [
{
"modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW",
"enabled": true
}
],
"variations": [
{
"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"
},
"sellable": true,
"stockable": true
}
},
{
"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"
},
"sellable": true,
"stockable": true
}
}
],
"product_type": "REGULAR"
}
}
],
"latest_time": "2020-06-10T03:23:41.067Z"
}You can combine a query with other search conditions to return the result that satisfies all the specified query expressions and search conditions.
The following cURL example shows how to call the SearchCatalogObjects endpoint to search for objects of the ITEM_VARIATION type matching their name attribute value to coffee, without including any related object:
Search catalog objects
{
"objects": [
{
"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": "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"
}
}
}
],
"related_objects": [
{
"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",
"product_type": "REGULAR"
}
},
{
"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",
"product_type": "REGULAR"
}
}
],
"latest_time": "2020-06-23T18:03:31.656Z"
}Because the include_related_objects flag is set to true, the related_objects is included in the result. If this flag isn't set or set to false, the related items aren't returned.
To search for catalog objects with a given attribute value starting with a specified text string, call SearchCatalogObject while supplying a prefix_query filter in the query parameter.
The following example searches for objects whose name attribute starts with the text of "sma":
Search catalog objects
{
"objects": [
{
"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"
},
"sellable": true,
"stockable": true
}
}
],
"latest_time": "2020-06-10T03:23:41.067Z"
}The response returns the Small item variation available for search at the time of the call. Notice that matching against the specified attribute value is case-insensitive.
As another example, try to search for objects with "happy" as a prefix to the name attribute value:
Search catalog objects
{
"objects": [
{
"type": "PRICING_RULE",
"id": "3GULP4ZWYKLJPEU6YPFFA2MC",
"updated_at": "2020-06-02T19:27:34.968Z",
"version": 1591126054968,
"is_deleted": false,
"present_at_all_locations": true,
"pricing_rule_data": {
"name": "Happy Hour",
"time_period_ids": [
"DE4AZASOM7WGFIJSBZEWEMRG"
],
"discount_id": "GAJS57APBZX445NOYMINZZUC",
"match_products_id": "IAPA75F4ZUBMCF6IVIP7FC2E",
"application_mode": "AUTOMATIC"
}
}
],
"latest_time": "2020-06-10T03:23:41.067Z"
}This call returns a catalog pricing rule object named Happy Hour, which is the only matching object in this catalog.
Search with a text_query filter is like free-text search that returns objects by matching searchable attribute values of objects against the specified list of keywords. The search result doesn't depend on the order of the keywords specified.
The following example uses a text_query filter to search for objects containing the words "one", "free", and "drink" in any of their searchable attributes:
Search catalog objects
{
"objects": [
{
"type": "PRICING_RULE",
"id": "7MZW6RTZ2FSDDPPJLLAQ3WF4",
"updated_at": "2020-06-02T00:04:28.467Z",
"version": 1591056268467,
"is_deleted": false,
"present_at_all_locations": true,
"pricing_rule_data": {
"name": "Buy One Drink Get One Free Pricing Rule",
"discount_id": "FJYAGNWCJSX42774FCLQZ25Z",
"match_products_id": "NS5Z4ZNTUPVESPT6JBJWU3IZ",
"exclude_products_id": "WSPNQO56GCYDCFSQWXS534TS",
"application_mode": "AUTOMATIC"
}
}
],
"latest_time": "2020-06-23T18:03:31.656Z"
}The result is a CatalogPricingRule object named "Buy One Drink Get One Free Pricing". Apparently, this is the only object matching the query filter in this particular catalog.
The SearchCatalogObjects endpoint also supports searching for catalog items with the specified modifier list enabled. To do so, use the items_for_modifier_list_query filter in the query parameter. The filter defines the IDs of modifier lists enabled for the items.
The following example searches for the catalog items that have a specific modifier list (["ZVSGY6U63IGCZQL4IOPZAKYW"]) enabled. The specified modifier list is named Milk Options and contains two modifiers defined for the Skim Milk and Whole Milk variations enabled for the item.
Search catalog objects
The successful response returns the result similar to the following, if the queried objects are found:
{
"objects": [
{
"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",
"modifier_list_info": [
{
"modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW",
"enabled": true
}
],
"variations": [
{
"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"
}
}
},
{
"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"
}
}
}
],
"product_type": "REGULAR"
}
}
],
"latest_time": "2020-06-10T03:23:41.067Z"
}The search returns the Coffee item for which the specified modifier list (as identified by the modifier list ID of ZVSGY6U63IGCZQL4IOPZAKYW) is enabled.
When a catalog object is deleted, its is_deleted attribute is set to true. To retrieve a deleted object, you can set include_deleted_objects to true when calling the SearchCatalogObjects endpoint and then inspect the result to filter those with "is_deleted": true.
The following example searches for the catalog items that can include the deleted ones:
Search catalog objects
The successful response returns deleted catalog items, if any, along with active ones. This is shown in the following example:
{
"objects": [
{
"type": "ITEM",
"id": "BDWYGZO5QQWWEVFV6PAEP3BS",
"updated_at": "2021-05-19T03:58:12.86Z",
"version": 1621396692860,
"is_deleted": false,
"custom_attribute_values": {
"sq0ids-tDPX2MkYWBjjQSKR88V-BQ:online_readiness": {
"name": "online_readiness",
"custom_attribute_definition_id": "FSHYJTVR2BZ3E3LDZFCTD5AU",
"type": "NUMBER",
"number_value": "0.22118",
"key": "sq0ids-tDPX2MkYWBjjQSKR88V-BQ:online_readiness"
}
},
"present_at_all_locations": true,
"image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
"item_data": {
"name": "adventure",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "PRAVBIFA4IDWI3IPO6KQVV2B",
"updated_at": "2020-11-02T21:25:44.14Z",
"version": 1604352344140,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "BDWYGZO5QQWWEVFV6PAEP3BS",
"name": "8-day explore",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 250000,
"currency": "USD"
},
"transition_time": 0,
"stockable": true
}
}
],
"product_type": "APPOINTMENTS_SERVICE",
"skip_modifier_screen": false
}
},
{
"type": "ITEM",
"id": "I4BKTYZ3J4JF3PRWVAARFXOG",
"updated_at": "2020-11-02T21:34:50.997Z",
"version": 1604352890997,
"is_deleted": true,
"present_at_all_locations": true,
"image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
"item_data": {
"name": "Virtual adventure",
"product_type": "APPOINTMENTS_SERVICE",
"skip_modifier_screen": false
}
}
]
}