Categories: Sample Use Cases and Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Create category and subcategory

Help merchant organize their hierarchy by creating new categories and subcategories.

1. To create new category call Create Category endpoint. In the request body in addition to category you need to pass treeReference to specify the tree in which the category will be created. The category will be created in the top nesting level of the tree.

Save category.id from response.

2. To create subcategory within the newly created category call Create Category endpoint again. This time, include the parentCategory.id to specify the parent category that will be assigned. The treeReference will be the same as you sent in step 1.

Replace <parentCategoryId> with category id from response of step 1.

Add and arrange items in category

Help merchant to organize and classify their items by using categories. In this scenario, you will assign set of items to a category and arrange them in a specific order.

1. Add selected items to category by calling Bulk Add Items To Category endpoint.

In the request path, include category.id that you received in response of previous scenario. In the request body treeReference will also be the same and in items you can send all items that you want to add to category, Each item is referenced by pair of appId and catalogItemId.

3. After adding the items to the category, you can rearrange them for example to promote some items to be displayed in the beginning. Note that you can arrange up to 100 items, more items can be added, but you cannot control arrangement of them. Call Set Arranged Items endpoint. Pass exactly same params as in step 1 but now items must be in desired order in which you want to see them.
4. To display all items that belong to given category in the specified arrangement from previous step, use List Items In Category endpoint. In the request path, include same category.id from previous steps and in the request body, send the following:

Move subcategory to a different position within a parent category

Merchant may want to change the position of a category in the hierarchy.

1. Use the Create Category endpoint to create an additional subcategory within the parent category. In the request body as part of the category you need to also provide parentCategory.id to specify the parent category that will be assigned.

Save category.id from response.

2. To move the category to a different position in same parent category call Move Category endpoint. In the request path, include the category.id of the category you want to move. In the request, provide the parentCategoryId and specify position as FIRST to move the subcategory to the beginning.

Replace <parentCategoryId> with category id from response of previous scenarios.

Find all subcategories of a category

In this scenario, you want to retrieve a list of all subcategories that belong to a specific parent category, in the correct order. This is useful for traversing the category hierarchy.

Use the Search Categories endpoint. In the request body, include the parentCategory.id in the filter parameter and sort by parentCategory.index in ascending order:

Replace <parentCategoryId> with parent category id from previous scenarios.