Call the SearchCatalogObjects Endpoint

Learn how to programmatically search for objects of any type.

Overview

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_query filter of the CatalogQueryExact type returns any types of objects matching a specified attribute name and value exactly.
A prefix_query filter of the CatalogQueryPrefix type returns any types of objects matching a specified prefix of a given attribute value.
A range_query filter of the CatalogQueryRange type returns any types of objects matching a specified numerical range of a given attribute value.
A text_query filter of the CatalogQueryText type returns any types of objects matching specified keywords against searchable attribute values. Searchable attributes include name and description.
A sorted_attribute_query expression of the CatalogQuerySortedAttribute type sorts returned results in a specified order by a specified attribute.
An items_for_tax_query filter of the CatalogQueryItemsForTax type returns items with specified tax payer IDs.
An items_for_modifier_list_query filter of the CatalogQueryItemsForModifierList type returns items enabled with specified modifier lists as identified by their IDs.
An items_for_item_options filter of the CatalogQueryItemsForItemOptions type returns items with specified item options as identified by their IDs.
An items_variations_for_item_option_values_query filter 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_time attribute returns objects last modified since the specified time.
An include_category_path_to_root Boolean attribute includes a path_to_root list for each returned category instance if set to true. This attribute is useful if objects in the catalog belong to categories nested within other categories. If set to true, include_deleted_objects must be set to false. Both properties cannot be true at the same time.
An include_deleted_objects Boolean attribute returns deleted objects in the results list (true) or not (false, the default). If set to true, include_category_path_to_root must be set to false. Both properties cannot be true at the same time.
An include_related_objects attribute of a Boolean flag returns (true) or not (false) objects related to those matching other specified query filters.
An object_types attribute returns objects of the specified types matching other specified query filters.

Important

A SearchCatalogObjects request fails if both include_deleted_objects and include_category_path_to_root parameters are set to true. Only one of the two attributes can be true at a time.

Unlike with the SearchCatalogItems endpoint, you cannot call SearchCatalogObjects while using any custom attribute query filters.

Link to section

Search with an exact query filter

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.

Link to section

Request

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.

Link to section

Response

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"
}

Link to section

Search with a combination of query filters

You can combine a query with other search conditions to return the result that satisfies all the specified query expressions and search conditions.

Link to section

Request

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

Link to section

Response

{
  "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.

Link to section

Search with a prefix query filter

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.

Link to section

Request

The following example searches for objects whose name attribute starts with the text of "sma":

Search catalog objects

Link to section

Response

{
    "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.

Link to section

Request

As another example, try to search for objects with "happy" as a prefix to the name attribute value:

Search catalog objects

Link to section

Response

{
    "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.

Link to section

Search with a text query filter

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.

Link to section

Request

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

Link to section

Response

{
  "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.

Link to section

Search with items for a modifier list filter

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.

Link to section

Request

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

Link to section

Response

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.

Link to section

Search for deleted objects

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.

Link to section

Request

The following example searches for the catalog items that can include the deleted ones:

Search catalog objects

Link to section

Response

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
      }
    }
  ]
}

Docs

Call the SearchCatalogObjects Endpoint

On this page

Overview

Important

Search with an exact query filter

Request

Response

Search with a combination of query filters

Request

Response

Search with a prefix query filter

Request

Response

Request

Response

Search with a text query filter

Request

Response

Search with items for a modifier list filter

Request

Response

Search for deleted objects

Request

Response

On this page