Search for Items and Objects

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, and SKU.
• Custom attributes - Defined by the seller or developer, these attributes are specific to ITEM or ITEM_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 to true. However, it doesn't support custom attribute filters.

The key differences between the endpoints:

• SearchCatalogItems - Only searches ITEM and ITEM_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.

• Call the SearchCatalogItems Endpoint
• Call the SearchCatalogObjects Endpoint