Skip to main content

PIMS Categories Management API

POST 
/pim/manage/categories

This API provides a powerful tool set for adding, editing, and deleting categories, as well as configuring their attributes and filters for product data. You can add images to categories, change categories' hierarchy, and create new categories. With this API, you'll have everything you need to manage your products with ease!

To use this API, send a POST request with a JSON body. Set the action key in the JSON body to one of the following values:

  • listCategories: Returns comprehensive information about the category hierarchy in the PIM. Data Editor ApiKey permissions.
  • addCategory: Creates a new category. Data Manager ApiKey permissions.
  • editCategory: Modifies an existing category. Data Manager ApiKey permissions.
  • deleteCategory: Removes an existing category. Data Manager ApiKey permissions.

To perform actions on a category using editCategory or deleteCategory, use the unique internal identifier of the category in PIMS. Specify this value as the value of the id key in the JSON body.

When editing or adding category attributes, specify the required attributes' names and values in the JSON body in the format 'attribute name' = 'attribute value.'

If the action is successful, the API response will contain complete updated information about the modified or added category in JSON format. Otherwise, an Error will be returned, providing details on the cause in the status_message.

Please note the following important aspects of managing categories in PIM:

  • editCategory:

  • You cannot rename a category if there is a category with the same name under the same parent (a conflict will occur).

  • You can specify path or name parameters in the JSON body. If the path is specified, the name parameter will be ignored, and the category will be moved to a new location (if there are no conflicts). If a new category name is specified in the path, the category will be renamed (if there are no conflicts). If neither path nor name is specified, only specified category attributes will be updated, and the hierarchy will not change.

  • Adding filters used for filtering data by product attributes in the specified category:

  • To add or modify category filters, set the value of the cat_filters key in the JSON body. The value of cat_filters is an array of filters used to filter data by product attributes in this category.

The product attribute should not be a Collection and should be Filterable

  • You can specify multiple filters for different product attributes. The structure of each filter depends on its type and is strictly regulated.

  • Use the Example Value and JSON Schema provided in the API documentation to build your filter creation request.

  • When adding or modifying filters, product attribute values specified as ranges or lists for the filter will be automatically recalculated based on all products in the PIMS system.

  • deleteCategory:

  • You can only delete a category after deleting all child categories.

Request​

Responses​

success