Category Service Tutorials

How to create a category

info

Category names and descriptions are localized. When creating a new category, you can specify the category name and descriptions in multiple languages.

Looking for more info on localization? Check out Standard practices.

Root categories vs. subcategories

If you want to create a root category, choose one from the following:

Omit the parentId element.
Set the parentId element to "null".
Set the parentId element to "root".

If you want to create a subcategory, include the parentId of the root category in the request body. To create a new category, you need to send a request to the Creating a new category endpoint.

warning

The localizedSlug field must not contain any diacritics.

How to assign a product to a category

You can assign resources, such as products, to particular categories.

Before you start

Make sure you have already finished the following tutorials:

Assign a product to a category

To assign a product to a category, you need to send a request to the Assigning a resource to a category endpoint and do the following:

Set the ref.type field to "PRODUCT".
Provide the product ID in the ref.id field.

Retrieve the category assignments

To check whether the resource was properly assigned to the category, you can send a request to the Retrieving resources assigned to a category endpoint.

How to delete resource assignments

You can delete all resources assigned to a particular category, or just one specific assignment.

attention

As a result of this procedure, only category assignments are deleted; the categories and resources themselves remain in the database.

Option one: Delete all product assignments

To delete all assignments for a specific category, you need to send a request to the Deleting all category assignments endpoint and set the assignmentType query parameter to PRODUCT.

Option two: Delete a specific product assignment

To delete only a specific assignment, you need to send a request to the Deleting a category assignment by reference ID and enter the ID of the resource in the referenceId path parameter.

How to publish/unpublish a category

To publish or unpublish a category, you need to send a request to the Partially updating a category endpoint and set the published property to true or false.

How to build and manage category trees

Category trees are built every time you create or update a category. The parentId is the identifier of the root category. Depending on your needs, you can manage the order of categories in a category tree by modifying the parentId and position elements of a particular category.

Retrieving category trees

Option one: Retrieve a specific category tree

warning

It is only possible to retrieve a category tree for a root category. It is not possible to get it for a category that lies lower in a hierarchy.

To retrieve a specific category tree, you need to send a request to the Retrieving the category tree endpoint and provide the category ID in the categoryId path parameter.

Option two: Retrieve all category trees belonging to the tenant

To retrieve all category trees, you need to send a request to the Retrieving the category trees endpoint.

Option three: Retrieve a list of subcategories of a category

To retrieve a list of subcategories for a specific category, you need to send a request to the Retrieving subcategories for a category endpoint.

attention

You can limit the depth of retrieved subcategories with the depth parameter.

If set to 1, only direct children of the specified category are retrieved.
If not specified, all descendants of the specified category are retrieved.

Moving a category

You can move a category by modifying its parentId value.

attention

When you move a category, all its subcategories and assigned references move along with it.

To move a category to be a child of another category, you need to send a request to the Partially updating a category endpoint and provide the desired parent category ID in the parentId field.