Categorize Catalog Items

Applies to: Catalog API

Learn how to categorize items in a Square seller's catalog.

Link to section

Overview

Square lets sellers have their business products or services cataloged as CatalogItem objects. These objects are commonly referred to as items. For example, if a seller sells t-shirts, dress shirts, and coats, a T-Shirt item, a Dress Shirt item, and a Coat item might be created in the seller's catalog. Similarly, if the seller provides services for career development coaching and professional skill training, a Career Coaching item and a Professional Training item might be created in the seller's catalog.

To facilitate managing and displaying the products for sale or services for hire, the seller can have the items categorized. For example, the T-Shirt, Dress Shirt, and Coat items can all be categorized under Clothing. When a customer visits the seller's store, they can be presented with all items under the Clothing category. The T-Shirt and Dress Shirt items can also be categorized under Shirts. The customer can then choose to browse only t-shirts or dress shirts under the Shirts category.

Link to section

Item categories

With the Square API, categories are encapsulated by CatalogCategory objects. The CatalogCategory.name field provides a user-friendly description of the category. The name can also be used in applicable query filters to search for categories. Programmatically, a category is referenced by the CatalogCategory object ID.

An item can be in multiple categories. For example, the T-Shirt and Dress Shirt items are both under the Clothing and Shirts categories. A category can be nested within another category known as its parent category. The Shirts category is nested within the Clothing category. The Clothing category can in turn be nested within another category. This nesting can be repeated all the way to the top-level (or root) category.

Link to section

Work with categories

Categorizing an item using the Square API involves the following programming tasks:

  • Call UpsertCatalogObject to create one or more CatalogCategory instances and, for a nested category, set its parent category in the parent_category field.
  • Call UpsertCatalogObject to categorize an item by assigning one or more categories to the item's categories list. This can be done when the item is created or updated.

Working with categories consists of performing some or all of the following tasks:

  • Create a category.
  • Categorize an item by including a category in the categories list.
  • Retrieve a category of a specific ID. The result can include an applicable chain of hierarchical relationships, starting from the immediate parent to the root.
  • Search for categories using supported query filters.

In the following, you learn how to call the Square API to perform these programming tasks.

Link to section

Create root categories

To start from scratch, you need to create a CatalogCategory instance to represent a category of your choosing. The following code example creates a root category named Clothing.

The root category is without a parent category and is also known as the top-level category.

Link to section

Request: Create a top-level category

Upsert catalog object

Link to section

Response: Create a top-level category

The successful response includes a payload similar to the following:

Note the id value for the resulting CatalogCategory instance. You need it wherever this category is referenced.

Link to section

Create nested categories

Follow the previous steps to create the 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.

Link to section

Request: Create a nested category

Upsert catalog object

Link to section

Response: Create a nested category

The successful response includes a payload similar to the following:

Note the resulting category ID. You need it to reference this category later.

Link to section

Assign categories to items

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.

Link to section

Request: Assign Shirts and Clothing categories to the T-Shirt item

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.

Link to section

Response: Assign Shirt and Clothing categories to the T-Shirt item

The successful response includes a payload similar to the following:

Link to section

Retrieve categories

With created categories, remaining operations involve retrieving them for evaluation. You can 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, you specify the category ID as a path parameter and specify include_category_path_to_root as a query parameter.

When calling BatchRetrieveCatalogObjects, you set the category ID and include_category_path_to_root in the payload.

Link to section

Request: Retrieve a specific CatalogCategory object

The following example shows how to retrieve a CatalogCategory object by calling RetrievingCatalogObject:

Retrieve catalog object

Link to section

Response:

The successful response includes a payload similar to the following:

The root_category attribute in the response references the root of the category hierarchy the returned category is in.

If the returned category is the root, root_category is null, the path_to_root list is empty, and both aren't included in the response payload. However, the parent_category attribute isn't empty and contains the ordinal number describing the position of the top-level category among its peers.

Link to section

Search for categories

If you don't know the IDs of categories, you can find them by calling the SearchCatalogObjects endpoint using supported query filters.

Link to section

Search for nested categories

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.

Link to section

Request: Search for nested categories of a parent category

Search catalog objects

Link to section

Response

The successful response returns a payload similar to the following:

Link to section

Find top-level categories

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.

Link to section

Request: Find top-level category instances of a specified name.

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).

Link to section

Response

The successful response includes a payload similar to the following:

Notice that the returned parent_category object doesn't contain the id attribute because the top-level category doesn't have any parent. The ordinal attribute value, in the range of -2^52 to 2^52, corresponds to the order of the category among all the top-level ones.

Link to section

Find items of a category

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.

Link to section

Request: Find items of a category

Search catalog objects

Notice that you cannot use additional query filters with the set_query filter.

Link to section

Response

Link to section

See also