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:
| Filter | Purpose |
|---|---|
exact_query - CatalogQueryExact | Returns any types of objects matching an attribute name and value exactly. |
prefix_query - CatalogQueryPrefix | Returns any types of objects matching a prefix of an attribute value. |
range_query - CatalogQueryRange | Returns any types of objects matching a numerical range of an attribute value. |
text_query - CatalogQueryText | Returns any types of objects matching keywords against searchable attribute values. Searchable attributes include name and description. |
sorted_attribute_query - CatalogQuerySortedAttribute | Sorts returned results in a specified order by an attribute. |
items_for_tax_query - CatalogQueryItemsForTax | Returns items with specified catalog tax IDs. |
items_for_modifier_list_query - CatalogQueryItemsForModifierList | Returns items enabled with specified modifier lists as identified by their IDs. |
items_for_item_options - CatalogQueryItemsForItemOptions | Returns items with specified item options as identified by their IDs. |
items_variations_for_item_option_values_query - CatalogQueryItemVariationsForItemOptionValues | 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_category_path_to_rootBoolean attribute includes apath_to_rootlist for each returned category instance if set totrue. This attribute is useful if objects in the catalog belong to categories nested within other categories. If set totrue,include_deleted_objectsmust be set tofalse. - An
include_deleted_objectsBoolean attribute returns deleted objects in the results list (true) or not (false, the default). If set totrue,include_category_path_to_rootmust be set tofalse. - 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.
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.
You cannot call SearchCatalogObjects with 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 shown in the following examples.
This example searches for catalog objects with the name attribute with a value of coffee:
Search catalog objects
When using an exact query filter, the names of the attributes must match exactly with what you specify. However, the values of these attributes are matched without worrying about uppercase or lowercase letters.
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
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
As another example, try to search for objects with "happy" as a prefix to the name attribute value:
Search catalog objects
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
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
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