Applies to: Catalog API
Learn how to categorize items in a Square seller's catalog.
Square allows sellers to list their business products and services as CatalogItem objects, also known as items. For example, if a seller offers t-shirts, dress shirts, and coats, they create a T‑Shirt item, a Dress Shirt item, and a Coat item in their catalog. Similarly, if the seller offers career coaching and professional training, they create a Career Coaching item and a Professional Training item.
To help manage and display products and services, sellers can categorize items. For example, T‑Shirt, Dress Shirt, and Coat items can be grouped under Clothing. When a customer browses the online store, they can see all items in the Clothing category. T-Shirt and Dress Shirt items can also be grouped under Shirts, allowing customers to browse only t-shirts or dress shirts in that category.
With the Square API, categories are represented by CatalogCategory objects. The CatalogCategory.name field provides a user-friendly name for the category. This name can be used in query filters to search for categories. Each category is identified by its CatalogCategory object ID.
An item can be in multiple categories. For example, T-Shirt and Dress Shirt items can be in both Clothing and Shirts categories. A category can also be nested within another category, called its parent category. For example, the Shirts category is nested within the Clothing category. This nesting can continue all the way up to the top-level (or root) category.
Categorizing an item using the Square API involves the following tasks:
- Call BatchUpsertCatalogObjects to create one or more
CatalogCategoryinstances and, for a nested category, set its parent category in theparent_categoryfield. - Call
UpsertCatalogObjectto categorize an item by assigning one or more categories to the item's categories list. You can do this when you're creating or updating the item.
To work with categories, your application performs some or all of these tasks after you create a category:
- Categorize an item by including a category in the
categorieslist. - Retrieve a category by its ID. The result can show the chain of relationships from the immediate parent category up to the root category.
- Search for categories using query filters.
The following sections detail how to use the Square API to perform these programming tasks.
Create a root (top-level) category for all clothing-related categories. The following code example creates a root category named Clothing:
Upsert catalog object
Now that you've created a root category for clothing, create a Shirt category, setting the name attribute of the CatalogCategory object to Shirts. To nest this category under the Clothing category, set the parent_category attribute to reference the ID of the parent category.
Upsert catalog object
Using the Square API, categorizing an item consists of calling UpsertCatalogObject to assign an existing category to the item. The item can be a new or existing one.
The following example creates a T-Shirt item of the Clothing and Shirts categories in three variations. Before making the following request, make sure you have the IDs of the Clothing and Shirts categories.
Upsert catalog object
To create the Dress Shirt item (with Small, Medium, and Large variations) and categorize the item as Shirts and Clothing, follow the previous example, changing the name and ID attributes to align with the dress shirt.
To create Coat items (also with Small, Medium, and Large variations) and categorize the item as Clothing, follow the previous example, changing the name and ID attributes to those of the coat and removing the Shirts category from the categories list.
To get a catalog object, call RetrieveCatalogObject or BatchRetrieveCatalogObjects to retrieve the CatalogCategory object of a specific category ID.
If the category is nested within other categories, you can ask for the category nesting path to be returned as part of the results. To do so, set include_category_path_to_root to true in the request.
When calling RetrieveCatalogObject, specify the category ID as a path parameter and specify include_category_path_to_root as a query parameter.
When calling BatchRetrieveCatalogObjects, set the category ID and include_category_path_to_root in the payload.
The following example shows how to retrieve a CatalogCategory object by calling RetrievingCatalogObject:
Retrieve catalog object
If you don't know the IDs of categories, you can find them by calling the SearchCatalogObjects endpoint using supported query filters.
To search for categories nested under a parent category, you can use the exact_query filter on the nested categories' parent_category attribute to return the categories that match the specified parent category ID.
The following example finds the categories nested within the Clothing category with the ID of AINQ7RLOYWXL5QLIMLIXT5XF:
Search catalog objects
Notice that the is_top_level attribute is of the Boolean type. However, the Boolean type of filters isn't currently supported. As a workaround, you can use a range_query filter against the is_top_level attribute with the minimum and maximum values both set to 1 (the integer representation of the logical true).
You can further limit the result set with additional query filters.
The following example finds top-level CatalogCategory instances named Clothing, using a range_query filter to match results by the is_top_level attribute of the Boolean type and an exact_query filter to further match results by the name attribute of the string type.
Search catalog objects
To return nested categories when is_top_level is false, set both attribute_max_value and attribute_min_value to 0 (the integer equivalent to the logical false).
To find items of a category, call SearchCatalogObjects for the ITEM type of objects while using the set_query filter to match the categories attribute against the specified category ID.
Search catalog objects
Notice that you cannot use additional query filters with the set_query filter.