Search for Items and Objects
A Square catalog can contain objects of various types, including for example
DISCOUNT. As more objects of different types are added to the catalog, it is 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
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
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
truereturns deleted catalog objects. This endpoint does not 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 does not support the
include_deleted_objects filter, while the
SearchCatalogObjects endpoint supports the filters to return deleted objects.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.