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 catalog searches, 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
ITEM
orITEM_VARIATION
types 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 only searches among catalog items or item variations and uses 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 search properties, including CatalogQuery. It can return deleted objects if the
include_deleted_objects
filter is set totrue
. However, it doesn't support custom attribute filters.
The key differences between the endpoints:
- SearchCatalogItems - Only searches
ITEM
andITEM_VARIATION
object types, supports custom attribute filters, and offers flexible and expressive query expressions. - SearchCatalogObjects - Searches all object types and returns deleted objects but lacks support for custom attribute filters.
The 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.