Categories organize your product assortment within your ecommerce. They work as hierarchical levels of product classification, making your client’s search for a product easier and keeping your store organized.

The category tree is the backbone of the Catalog, so it needs to be carefully planned and validated before importing to VTEX.

We strongly recommend starting to work on the category tree by creating a table similar to this one:

The idea behind this template is to allow easy visualization of how the tree is organized and how the specifications are being presented.

VTEX does not limit the number of categories that can be created. We strongly recommend having a maximum of three levels of categories.

• Moving categories: Although it is possible to move categories to different levels (higher/lower) and/or different departments, this is too risky because of the specifications attached to this category. This action can negatively affect product information, because products can inherit not only the previous specifications but also the new ones. To avoid issues, we recommend following the workaround described in Deactivating and reorganizing categories.
• Deleting categories: You cannot delete a category unless you make a full cleanup of the catalog. This means you cannot delete categories unless you clear the entire catalog.

All specifications registered in the upper levels of the hierarchy are inherited by the lower categories. In the example above, we have what we call the root category "level zero". This means that all specs registered at this level (Gender, Simple Color, and Country) will be inherited by level 1.

Note that the Shirt category (level 2) has the Style field as a specification. This means that the product contained in this category will have as attributes the Style field and all others defined in the upper level, in this case, the root level.

Products must be associated with the categories at the lowest level of the category tree. In this example, they must be associated with the category: Jeans with Pants or Polo with Shirt.

Creating a category is the most basic configuration you must do in Catalog. For a product to exist, it must have a category associated with it.

To create a category, one can use the Create category endpoint. See the request body example below of the creation of a category called Clothing:

Request body

Response body

In this example, the created category is a parent category, which means that it is not inside another category. A parent category can have subcategories, or children categories, associated with it. To create a subcategory, you must insert the parent category ID on the "FatherCategoryId".

Do not forget to activate the categories, otherwise the products will not be indexed and thereafter will not be displayed on the website.

You can edit an existing category by using the Update Category endpoint.

You can get information of all the category tree or just some specific level by using the Get Category Tree endpoint.

You can get information about a specific category by using the Get Category by ID endpoint.

See below the answer to some frequently asked questions.

It is not common for the customer to change the category tree once it is defined. Usually, specific changes may be required and can be made manually under VTEX Admin rather than having one more integration to take care of. Potentially we can find some cases where the category tree is built progressively according to the evolution of the store. But this typically happens during the validation of a new business. In that case, having category integration can be useful.

• Title
• Description

• The Title should be about 55 to 60 characters long.
• When writing the Meta Tag Description, aim for about 1-2 sentences (140-160 characters) long. Offer a compelling reason to visit the webpage. Add a clear call to action, address an emotional pain point, or offer a specific benefit to visitors.

Department, Category, and Subcategory titles can be customized using VTEX Intelligent Search. So on the search navigation bar, the store can present different titles for each category level.