Create, update, and query catalog custom attribute definition objects in Square. These define custom metadata fields that can be attached to other catalog objects.

Table Specific Information

CatalogCustomAttributeDefinitions returns only the CUSTOM_ATTRIBUTE_DEFINITION objects in the Square catalog. These objects define custom metadata fields that can be attached to other catalog objects.

The Catalog table is the generic counterpart. It returns objects of every catalog type in a single result set, and rather than giving each type its own columns it carries the type specific fields as a JSON document in the column matching the row type: ItemData for an item, CategoryData for a category, CustomAttributeDefinitionData for a custom attribute definition, and so on. Use Catalog to search across types or when the type is not known in advance, and use CatalogCustomAttributeDefinitions or another type specific table to work with one type through individual columns.

Because CatalogCustomAttributeDefinitions is restricted to CUSTOM_ATTRIBUTE_DEFINITION objects, a search that matches only other catalog types returns no rows here. Run the same search against Catalog to see those matches.

Select

The add-in 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 add-in.

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

Retrieve all catalog custom attribute definitions:

SELECT * FROM CatalogCustomAttributeDefinitions

Filter on Id to retrieve specific definitions. Id = fetches a single definition 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 Id, Name, Key FROM CatalogCustomAttributeDefinitions WHERE Id = 'custom_attr_1'

SELECT Id, Name, Key FROM CatalogCustomAttributeDefinitions WHERE Id IN ('custom_attr_1', 'custom_attr_2')

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, Name, UpdatedAt FROM CatalogCustomAttributeDefinitions WHERE UpdatedAt > '2025-01-01T00:00:00Z'

Set IncludeDeletedObjects to true to return definitions that have been deleted. A deleted definition reports IsDeleted as true.

SELECT Id, Name, IsDeleted FROM CatalogCustomAttributeDefinitions WHERE IncludeDeletedObjects = true

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

SELECT Id, Name FROM CatalogCustomAttributeDefinitions WHERE SearchText = 'Allergen'

Use IN to supply up to three keywords. Square combines them with AND and matches them in any order. Square rejects a fourth keyword with the error ARRAY_LENGTH_TOO_LONG, reporting that the collection must have at most 3 items.

SELECT Id, Name FROM CatalogCustomAttributeDefinitions WHERE SearchText IN ('Allergen', 'Info')

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 add-in 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.

Because this table returns only CUSTOM_ATTRIBUTE_DEFINITION objects, a search type that yields another catalog type produces no rows here even when it matches. The search types that return other types are 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 — run those against Catalog or the appropriate type-specific tables.

Match an attribute exactly, or by prefix:

SELECT Id, Name FROM CatalogCustomAttributeDefinitions WHERE Query = '{"exact_query":{"attribute_name":"name","attribute_value":"Allergen Info"}}'

SELECT Id, Name FROM CatalogCustomAttributeDefinitions WHERE Query = '{"prefix_query":{"attribute_name":"name","attribute_prefix":"Aller"}}'

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, Name FROM CatalogCustomAttributeDefinitions 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, Name FROM CatalogCustomAttributeDefinitions WHERE Query = '{"sorted_attribute_query":{"attribute_name":"name","sort_order":"ASC"}}'

Match an attribute against a set of values. In Catalog the result set is the union of the matches across every type; here it is narrowed to the definitions among them.

SELECT Id, Name FROM CatalogCustomAttributeDefinitions WHERE Query = '{"set_query":{"attribute_name":"name","attribute_values":["Allergen Info","Nutrition"]}}'

Combine a filtering search with a sort in one CatalogQuery:

SELECT Id, Name FROM CatalogCustomAttributeDefinitions WHERE Query = '{"prefix_query":{"attribute_name":"name","attribute_prefix":"Aller"},"sorted_attribute_query":{"attribute_name":"name","sort_order":"DESC"}}'

The filters can be combined in a single WHERE clause. The add-in merges them into one request, with SearchText folded into the CatalogQuery next to whatever the Query column supplies.

SELECT Id, Name FROM CatalogCustomAttributeDefinitions WHERE SearchText = 'Allergen' AND Query = '{"sorted_attribute_query":{"attribute_name":"name","sort_order":"ASC"}}' AND IncludeDeletedObjects = true

Insert

To create a catalog custom attribute definition, you must specify the Id, Name, Type, AllowedObjectTypes, and Key columns. Note: the Type and Key fields cannot be modified after creation.

INSERT INTO CatalogCustomAttributeDefinitions (Id, Name, Type, Key, AllowedObjectTypes, SellerVisibility) VALUES ('#new-custom-attribute', 'Allergen Info', 'STRING', 'allergen-info', '["ITEM","ITEM_VARIATION"]', 'SELLER_VISIBILITY_READ_WRITE_VALUES')

Update

Modify the details of an existing catalog custom attribute definition by providing the Id. When updating, provide the Version to match the current version in the database. Note: Type and Key cannot be changed.

UPDATE CatalogCustomAttributeDefinitions SET Name = 'Updated Allergen Info', Description = 'Allergen information for this item', Version = 1 WHERE Id = 'custom_attribute_definition_id_here'

Delete

Delete a catalog custom attribute definition by providing the Id:

DELETE FROM CatalogCustomAttributeDefinitions WHERE Id = 'custom_attribute_definition_id_here'

Bulk Delete

The maximum BatchSize supported by CatalogCustomAttributeDefinitions for a delete is 200. Note that this is lower than the 1000 Ids a batch retrieve accepts, because Square caps its catalog batch delete separately.

Stage the Ids of the custom attribute definitions to remove in a TEMP table, then delete them in a single request. Only the Id is needed on each staged row, and a row that supplies no Id is rejected before the request is sent.

INSERT INTO CatalogCustomAttributeDefinitions#TEMP (Id) VALUES ('custom_attr_1')

INSERT INTO CatalogCustomAttributeDefinitions#TEMP (Id) VALUES ('custom_attr_2')

DELETE FROM CatalogCustomAttributeDefinitions WHERE EXISTS SELECT Id FROM CatalogCustomAttributeDefinitions#TEMP

A catalog batch delete succeeds even when only some of the Ids could be removed, and Square answers with the Ids it actually deleted. The add-in reports the outcome of every staged Id against that list, so query LastResultInfo#TEMP after the delete to see which rows were removed and which were not.

SELECT * FROM LastResultInfo#TEMP

Note: The staged form shown above is required to reach the bulk delete endpoint. A DELETE FROM CatalogCustomAttributeDefinitions WHERE Id = '...' statement removes the same custom attribute definition but issues one request per Id.

Columns

Name	Type	ReadOnly	Description
Id [KEY]	String	False	The custom attribute definition's ID.
UpdatedAt	Datetime	True	Date and time when the custom attribute definition was last modified.
IsDeleted	Boolean	False	If true, the object has been deleted from the database.
Version	Int64	False	The version of the object. When updating, the version supplied must match the version in the database.
PresentAtAllLocations	Boolean	False	If true, this object is present at all locations.
PresentAtLocationIds	String	False	A list of locations where the object is present.
AbsentAtLocationIds	String	False	A list of locations where the object is not present.
Name	String	False	The name of this definition for API and seller-facing UI purposes.
Description	String	False	Seller-oriented description of the meaning of this Custom Attribute, any constraints on its values, and how it should be used.
Type	String	False	The type of this custom attribute. Cannot be modified after creation. The allowed values are STRING, BOOLEAN, NUMBER, SELECTION, DATE_TIME.
AllowedObjectTypes	String	False	The set of Catalog Object Types that this Custom Attribute may be applied to. Valid values: ITEM, ITEM_VARIATION, MODIFIER, MODIFIER_LIST, CATEGORY.
SellerVisibility	String	False	The visibility of a custom attribute to sellers. The allowed values are SELLER_VISIBILITY_HIDDEN, SELLER_VISIBILITY_READ_WRITE_VALUES.
AppVisibility	String	False	The visibility of a custom attribute to applications other than the application that created the attribute. The allowed values are APP_VISIBILITY_HIDDEN, APP_VISIBILITY_READ_ONLY, APP_VISIBILITY_READ_WRITE_VALUES.
Key	String	False	The identifier of the custom attribute definition and its corresponding custom attributes. Must be 1-60 characters, alphanumeric, underscore, or hyphen only.
CreatedAt	Datetime	True	Date and time when the custom attribute definition was first created in the catalog.

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.
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. This table returns only CUSTOM_ATTRIBUTE_DEFINITION objects, so a search that matches other catalog types returns no rows. Do not set text_query here; this table builds it from the SearchText column.