Applies to: Catalog API
Learn how to search for catalog objects, including items or items variations.
A Square catalog can contain objects of various types, including for example ITEM, ITEM_VARIATION, CATEGORY, TAX, and DISCOUNT. As more objects of different types are added to the catalog, it's important to have more robust search capabilities to find the data most relevant to an application's need.
To enable such capabilities, the Catalog API supports the SearchCatalogItems and SearchCatalogObjects endpoints that can take one or more of the supported query filters.
Supported query filters help narrow the search scope by matching specified query conditions against object system attributes, searchable attributes, or any supported custom attributes:
- System attributes include a time when an object was created, the current object status (active or deleted), or an intent of whether to include related objects.
- Searchable attributes include
name,description,sku, and others. - Custom attributes are objects of the CatalogCustomAttributeDefinition type defined by the seller or an application developer and assigned to objects of the
ITEMorITEM_VARIATIONtype.
There are two Catalog API endpoints that can be used to search a Square catalog, depending on the types of catalog objects searched and query filters used:
- The SearchCatalogItems endpoint supports queries for catalog items or item variations with one or more supported query filters. This is especially useful if custom attribute values are assigned to items or item variations and custom attribute filters are used.
- The SearchCatalogObjects endpoint supports queries for catalog objects of any types using one or more supported query filters. Setting the
include_deleted_objectsfilter totruereturns deleted catalog objects. This endpoint doesn't support custom attribute filters.
The two endpoints take input of somewhat different formats. The query filters used for the two endpoints differ significantly from each other. Although the SearchCatalogObjects endpoint is more versatile to search for any object types, the SearchCatalogItems endpoint benefits from not only the added capability for search by custom attributes but also improved programming patterns for its flexibility and expressiveness of the query expressions.
The two endpoints also differ in how they handle deleted objects. The SearchCatalogItems endpoint doesn't support the include_deleted_objects filter, while the SearchCatalogObjects endpoint supports the filters to return deleted objects.
When a call to the SearchCatalogObjects or SearchCatalogItems endpoint is expected to return a large set of objects, you might need to use pagination to retrieve the results page by page.