Applies to: Catalog API
Learn how to search for catalog items of any product type or catalog objects of any type.
A Square catalog can include different types of objects, such as ITEM, ITEM_VARIATION, CATEGORY, TAX, and DISCOUNT. As the catalog grows, it's crucial to have strong search capabilities to find the most relevant data for an application's needs.
To support these search capabilities, the Catalog API offers the SearchCatalogItems and SearchCatalogObjects endpoints, which can use various query filters.
These filters help refine searches by matching conditions against the following attributes:
- System attributes - Such as the creation time of an object, its current status (active or deleted), and whether related objects should be included.
- Searchable attributes - Such as
name,description, andSKU. - Custom attributes - Defined by the seller or developer, these attributes are specific to
ITEMorITEM_VARIATIONtypes and are based on the CatalogCustomAttributeDefinition type.
The Catalog API offers two endpoints for searching a Square catalog, each suited to different needs:
SearchCatalogItems - This endpoint is designed for searching catalog items or item variations using various query filters, including custom attribute filters. It's particularly useful when items have custom attributes.
SearchCatalogObjects - This endpoint allows you to search for any type of catalog object using multiple query filters. It can return deleted objects if the
include_deleted_objectsfilter is set totrue. However, it doesn't support custom attribute filters.
The key differences between the endpoints:
- SearchCatalogItems - Supports custom attribute filters and offers flexible, expressive query expressions.
- SearchCatalogObjects - Searches all object types and returns deleted objects but lacks support for custom attribute filters.
Both endpoints use different input formats and query filters. If a search is expected to return many objects, pagination might be necessary to retrieve results in batches.