Returns a list of all CatalogObjects.

Table Specific Information

Catalog returns every object in the Square catalog, whatever its type, as a single result set. The table is read-only. To create, modify, or remove catalog objects, use the type specific tables such as CatalogItems, CatalogCategories, CatalogTaxes, and CatalogModifierLists.

Select

The driver uses the Square API to filter the results by the following columns and operators while the rest of the filter is executed client-side within the driver.

• Id supports the following operators: =, IN.
• IncludeCategoryPathToRoot supports the following operator: =.
• IncludeDeletedObjects supports the following operator: =.
• IncludeRelatedObjects supports the following operator: =.
• Query supports the following operator: =.
• SearchText supports the following operators: =, IN.
• Type supports the following operators: =, IN.
• UpdatedAt supports the following operator: >.

Retrieve every catalog object:

SELECT * FROM Catalog

The Type column identifies what each row is, and the fields specific to that type are returned as JSON in the matching data column. An ITEM row populates ItemData, a CATEGORY row populates CategoryData, a TAX row populates TaxData, and so on. Only the column that matches the row type is populated; the rest are null.

SELECT Id, Type, ItemData, CategoryData, TaxData FROM Catalog

Filter on Id to retrieve specific objects. Id = fetches a single object directly. Id IN is served by the batch retrieve endpoint in a single request rather than one request per Id; the endpoint takes up to 1000 Ids per request, so a longer list is split across as many requests as needed.

SELECT * FROM Catalog WHERE Id = 'D7SQKLAOZB6626JJNN4OV3OS'

SELECT * FROM Catalog WHERE Id IN ('D7SQKLAOZB6626JJNN4OV3OS', 'RBBPBDDSWHILRTI4VGPZJEZW')

Filter on Type to restrict the search to one or more catalog types:

SELECT Id, Type FROM Catalog WHERE Type = 'ITEM'

SELECT Id, Type FROM Catalog WHERE Type IN ('TAX', 'DISCOUNT')

UpdatedAt supports only the > operator, which Square applies as the start of the search window. Equality and the upper bound operators are not supported.

SELECT Id, Type, UpdatedAt FROM Catalog WHERE UpdatedAt > '2025-01-01T00:00:00Z'

Set IncludeDeletedObjects to true to return objects that have been deleted from the catalog. A deleted row reports IsDeleted as true, and its UpdatedAt equals the time it was deleted.

SELECT Id, Type, IsDeleted, UpdatedAt FROM Catalog WHERE IncludeDeletedObjects = true

Set IncludeRelatedObjects to true to have Square also load the objects referenced by the matched objects, such as the categories and taxes an item points to. Square returns these in a separate field of the response, so they do not appear as extra rows in the result set. The filter is useful when a downstream integration relies on Square having resolved those references.

SELECT Id, Type FROM Catalog WHERE Type = 'ITEM' AND IncludeRelatedObjects = true

Set IncludeCategoryPathToRoot to true to add a path_to_root list to each returned category. The list starts with the immediate parent of the category and ends with its root category, and it is returned inside CategoryData. The filter applies only to rows whose Type is CATEGORY, and Square omits path_to_root for a category that is already top level.

SELECT Id, Type, CategoryData FROM Catalog WHERE Type = 'CATEGORY' AND IncludeCategoryPathToRoot = true

SearchText searches the searchable attributes of a catalog object, such as name, description, and SKU. Matching is case-insensitive, and keywords of fewer than three alphanumeric characters are ignored.

SELECT Id, Type FROM Catalog WHERE SearchText = 'Heavenly'

Use IN to supply up to three keywords. Square combines them with AND and matches them in any order, so the following query returns only the objects whose searchable text contains both words.

SELECT Id, Type FROM Catalog WHERE SearchText IN ('Heavenly', 'Strike')

Square rejects a fourth keyword with the error ARRAY_LENGTH_TOO_LONG, reporting that the collection must have at most 3 items.

The Query column takes a Square CatalogQuery object, supplied as JSON, and gives access to every search Square offers. The following search types are available.

• exact_query matches an attribute against an exact value. Takes attribute_name and attribute_value.
• prefix_query matches an attribute against a leading substring. Takes attribute_name and attribute_prefix.
• range_query matches a numeric attribute against a range. Takes attribute_name, attribute_min_value, and attribute_max_value.
• sorted_attribute_query orders the results by an attribute. Takes attribute_name, sort_order, and optionally initial_attribute_value.
• set_query matches an attribute against any value in a set. Takes attribute_name and attribute_values.
• items_for_tax_query returns the items that use the given taxes. Takes tax_ids.
• items_for_modifier_list_query returns the items that use the given modifier lists. Takes modifier_list_ids.
• items_for_item_options_query returns the items that use the given item options. Takes item_option_ids.
• item_variations_for_item_option_values_query returns the item variations that carry the given item option values. Takes item_option_value_ids.
• modifiers_for_child_list_query returns the modifiers that nest the given modifier lists, matching a modifier whose child_modifier_list_ids contains any of the supplied IDs. Takes child_modifier_list_ids. This search type is in beta.

exact_query, prefix_query, range_query, and sorted_attribute_query may be set together in a single CatalogQuery. Each of set_query, items_for_tax_query, items_for_modifier_list_query, items_for_item_options_query, item_variations_for_item_option_values_query, and modifiers_for_child_list_query must be the only search type in the object.

Do not set text_query in the Query column if SearchText is also set: both write to the same search, and driver rejects the combination with an error instead of merging them. Express the whole text_query search inside the Query value, or drop it and filter with SearchText alone.

Match an attribute exactly, or by prefix:

SELECT Id, Type FROM Catalog WHERE Query = '{"exact_query":{"attribute_name":"name","attribute_value":"TestName1"}}'

SELECT Id, Type FROM Catalog WHERE Query = '{"prefix_query":{"attribute_name":"name","attribute_prefix":"TestName"}}'

Match a numeric attribute against a range. The attribute_name must be an attribute Square indexes for search, such as ordinal; Square reports Unknown attribute definition name for anything it does not recognize.

SELECT Id, Type FROM Catalog WHERE Query = '{"range_query":{"attribute_name":"ordinal","attribute_min_value":0,"attribute_max_value":100}}'

Order the results by an attribute. Square preserves this ordering in the result set.

SELECT Id, Type FROM Catalog WHERE Query = '{"sorted_attribute_query":{"attribute_name":"name","sort_order":"ASC"}}'

Match an attribute against a set of values. The result set is the union of the matches, so it can span several catalog types.

SELECT Id, Type FROM Catalog WHERE Query = '{"set_query":{"attribute_name":"name","attribute_values":["TestName1","Heavenly Strike"]}}'

Find the items that reference a given tax, modifier list, or item option. These searches return only items, never the referenced object itself.

SELECT Id, Type FROM Catalog WHERE Query = '{"items_for_tax_query":{"tax_ids":["RBBPBDDSWHILRTI4VGPZJEZW"]}}'

SELECT Id, Type FROM Catalog WHERE Query = '{"items_for_modifier_list_query":{"modifier_list_ids":["NXSN3MCXIK7VKWGWPOS7DHA4"]}}'

SELECT Id, Type FROM Catalog WHERE Query = '{"items_for_item_options_query":{"item_option_ids":["K3C42O2ES4235E5XK3JHEJ6Q"]}}'

Find the item variations that carry a given item option value:

SELECT Id, Type FROM Catalog WHERE Query = '{"item_variations_for_item_option_values_query":{"item_option_value_ids":["L3JZSQKCIEQ5YPBQ7SIDIFAJ"]}}'

Find the modifiers that nest a given modifier list:

SELECT Id, Type FROM Catalog WHERE Query = '{"modifiers_for_child_list_query":{"child_modifier_list_ids":["NXSN3MCXIK7VKWGWPOS7DHA4"]}}'

Combine a filtering search with a sort in one CatalogQuery:

SELECT Id, Type FROM Catalog WHERE Query = '{"prefix_query":{"attribute_name":"name","attribute_prefix":"Test"},"sorted_attribute_query":{"attribute_name":"name","sort_order":"DESC"}}'

The filters can be combined in a single WHERE clause. The driver merges them into one request: Type becomes the list of object types, the three include columns become their own flags, and SearchText is folded into the CatalogQuery next to whatever the Query column supplies.

SELECT Id, Type, IsDeleted FROM Catalog WHERE Type = 'CATEGORY' AND SearchText = 'Heavenly' AND Query = '{"sorted_attribute_query":{"attribute_name":"name","sort_order":"ASC"}}' AND IncludeDeletedObjects = true AND IncludeRelatedObjects = true AND IncludeCategoryPathToRoot = true

Columns

Name	Type	Description
Id [KEY]	String	A unique identifier to reference this object in the catalog.
Type	String	The catalog type of this object. The allowed values are ITEM, IMAGE, CATEGORY, ITEM_VARIATION, TAX, DISCOUNT, MODIFIER_LIST, MODIFIER, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN_VARIATION, ITEM_OPTION, ITEM_OPTION_VAL, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNTS_SETTINGS, SUBSCRIPTION_PLAN, AVAILABILITY_PERIOD.
UpdatedAt	Datetime	Last modification timestamp in RFC 3339 format.
Version	Int64	The version of the object.
IsDeleted	Boolean	If true, the object has been deleted from the database. When deleted, the UpdatedAt field will equal the deletion time.
PresentAtAllLocations	Boolean	If true, this object is present at all locations (including future locations), except where specified in the AbsentAtLocationIds field. If false, this object is not present at any locations (including future locations), except where specified in the PresentAtLocationIds field. If not specified, defaults to true.
PresentAtLocationIds	String	A list of locations where the object is present, even if PresentAtAllLocations is false.
AbsentAtLocationIds	String	A list of locations where the object is not present, even if PresentAtAllLocations is true.
ItemData	String	Structured data for a CatalogItem, set for CatalogObjects of type ITEM. This field is populated only if the Catalog type is ITEM.
CategoryData	String	Structured data for a CatalogCategory, set for CatalogObjects of type CATEGORY. This field is populated only if the Catalog type is CATEGORY.
ItemVariationData	String	Structured data for a CatalogItemVariation, set for CatalogObjects of type ITEM_VARIATION. This field is populated only if the Catalog type is ITEM_VARIATION.
TaxData	String	Structured data for a CatalogTax, set for CatalogObjects of type TAX. This field is populated only if the Catalog type is TAX.
DiscountData	String	Structured data for a CatalogDiscount, set for CatalogObjects of type DISCOUNT. This field is populated only if the Catalog type is DISCOUNT.
ModifierListData	String	Structured data for a CatalogModifierList, set for CatalogObjects of type MODIFIER_LIST. This field is populated only if the Catalog type is MODIFIER_LIST.
ModifierData	String	Structured data for a CatalogModifier, set for CatalogObjects of type MODIFIER. This field is populated only if the Catalog type is MODIFIER.
TimePeriodData	String	Structured data for a CatalogTimePeriod, set for CatalogObjects of type TIME_PERIOD. This field is populated only if the Catalog type is TIME_PERIOD.
ProductSetData	String	Structured data for a CatalogProductSet, set for CatalogObjects of type PRODUCT_SET. This field is populated only if the Catalog type is PRODUCT_SET.
PricingRuleData	String	Structured data for a CatalogPricingRule, set for CatalogObjects of type PRICING_RULE. This field is populated only if the Catalog type is PRICING_RULE.
ImageData	String	Structured data for a CatalogImage, set for CatalogObjects of type IMAGE. This field is populated only if the Catalog type is IMAGE.
MeasurementUnitData	String	Structured data for a CatalogMeasurementUnit, set for CatalogObjects of type MEASUREMENT_UNIT. This field is populated only if the Catalog type is MEASUREMENT_UNIT.
SubscriptionPlanData	String	Structured data for a CatalogSubscriptionPlan, set for CatalogObjects of type SUBSCRIPTION_PLAN. This field is populated only if the Catalog type is SUBSCRIPTION_PLAN.
ItemOptionData	String	Structured data for a CatalogItemOption, set for CatalogObjects of type ITEM_OPTION. This field is populated only if the Catalog type is ITEM_OPTION.
ItemOptionValueData	String	Structured data for a CatalogItemOptionValue, set for CatalogObjects of type ITEM_OPTION_VAL. This field is populated only if the Catalog type is ITEM_OPTION_VAL.
CustomAttributeDefinitionData	String	Structured data for a CatalogCustomAttributeDefinition, set for CatalogObjects of type CUSTOM_ATTRIBUTE_DEFINITION. This field is populated only if the Catalog type is CUSTOM_ATTRIBUTE_DEFINITION.
SubscriptionPlanVariationData	String	Structured data for a CatalogSubscriptionPlanVariation, set for CatalogObjects of type SUBSCRIPTION_PLAN_VARIATION. This field is populated only if the Catalog type is SUBSCRIPTION_PLAN_VARIATION.

Pseudocolumns

Pseudo column fields are used in the WHERE clause of SELECT statements (unless stated otherwise) and offer a more granular control over the tuples that are returned from the data source.

Name	Type	Description
IncludeDeletedObjects	Boolean	If true, deleted objects are included in results.
IncludeRelatedObjects	Boolean	If true, the query also retrieves objects that are related to the matched objects, such as the categories and taxes referenced by an item. Related objects are returned by the API in a separate field and are not surfaced as rows in this table.
IncludeCategoryPathToRoot	Boolean	If true, each returned category includes its path_to_root list, which starts with the immediate parent of the category and ends with its root category. The list is returned within CategoryData and applies only to rows whose Type is CATEGORY.
SearchText	String	A keyword to search for across the searchable attributes of a catalog object, such as name, description, and SKU. Matching is case-insensitive, and keywords of fewer than three alphanumeric characters are ignored. Use IN to supply up to three keywords, which are combined with AND in any order; Square rejects a fourth.
Query	String	A Square CatalogQuery object, supplied as JSON, giving full access to every search Square offers. Any of exact_query, prefix_query, range_query, sorted_attribute_query, and text_query may be set together. Each of set_query, items_for_tax_query, items_for_modifier_list_query, items_for_item_options_query, item_variations_for_item_option_values_query, and modifiers_for_child_list_query must be the only search set. Do not set text_query here; this table builds it from the SearchText column.