PIMS Categories Management API

POST 
/pim/manage/categories

• Requires Data Editor, Data Manager ApiKey permissions.

• Example URI: https://instancename.piminto.com/api/en-us/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

application/json

Body

required

oneOf

List Categories

action stringrequired

Possible values: [listCategories]

Add Category

action stringrequired

Possible values: [addCategory]

path stringrequired

String representing the full path of the category, including parent categories, separated by '>'. For example, "Parent Name > Child-1 Name >Child-2 Name" This value represents a category named "Child-2 Name" that belongs to the "Child-1 Name" subcategory, which in turn belongs to the "Parent Name" category.

Edit Category

action stringrequired

Possible values: [editCategory]

id integerrequired

Unique identifier of the category for which the "edit" action is performed.

data object

Metadata associated with the category. Extendable

status string

Describes the activity status of the category. In the context of GET API requests, categories are filtered based on their status, and only categories with the active status will be returned. If the status is not explicitly specified, the category is considered active by default and will be included in the query results.

cat_image string

The path for the image of the category.

cat_rank integer

A numerical classification for the category's rank.

cat_filters object[]

Is an array of filters used to filter data by attribute products in this category, and its structure and number of elements depend on the PIM settings. The following is an example of one possible structure.

Array [

anyOf

filter_dropdown

filter_name stringrequired

The name of the filter.

filter_values object[]required

An array of values for the filter, with each item having a "label" and "value" option.

Array [

label stringrequired

The label option for the filter value.

value stringrequired

The value option for the filter value.

]

filter_var stringrequired

The attribute name by which products will be filtered within this category.

filter_type stringrequired

Possible values: [multiselect, dropdown]

The type of the filter.

filter_range_float

filter_name stringrequired

The name of the filter.

filter_values required

An object that contains the minimum and maximum attribute values allowed by the filter.

min stringrequired

max stringrequired

filter_var stringrequired

The attribute name by which products will be filtered within this category.

filter_type stringrequired

Possible values: [range_float]

The type of the filter.

]

cat_order integer

name string

Specify this parameter if you want to change the name of the category.

The name of the category.

path string

Specify this parameter if you want the category to be moved to a new location.

String representing the full path of the category, including parent categories, separated by '>'. For example, "Parent Name > Child-1 Name >Child-2 Name" This value represents a category named "Child-2 Name" that belongs to the "Child-1 Name" subcategory, which in turn belongs to the "Parent Name" category.

If the parameter 'path' is specified, the parameter 'name' is ignored.

Delete Category

action stringrequired

Possible values: [deleteCategory]

id integerrequired

Unique identifier of the category for which the "delete" action is performed.

Responses

200

success

application/json

Schema

Schema

oneOf
ListCategoriesResponse
data object[]required
Array [
id integerrequired
Automatically calculated value that represents a unique PIMS internal category ID. You can use to retrieve more details about the category.
cat_name stringrequired
The name of the category identified by categoryId.
cat_parent_id integerrequired
The relative path of the category that is calculated and uses '>' as a separator for the unique category ID.
cat_path_id stringrequired
The calculated relative path of the category, uses '>' as a unique category ID separator.
cat_path stringrequired
The calculated relative path of the category, uses '>' as a category name separator.
cat_order integerrequired
The proper sort order for the categories when displayed in a user interface.
cat_data objectrequired
Metadata associated with the category. Extendable
status string
Describes the activity status of the category. In the context of GET API requests, categories are filtered based on their status, and only categories with the active status will be returned. If the status is not explicitly specified, the category is considered active by default and will be included in the query results.
cat_image string
The path for the image of the category.
cat_rank integer
A numerical classification for the category's rank.
cat_filters object[]
Is an array of filters used to filter data by attribute products in this category, and its structure and number of elements depend on the PIM settings. The following is an example of one possible structure.
Array [
anyOf
filter_dropdown
filter_name stringrequired
The name of the filter.
filter_values object[]required
An array of values for the filter, with each item having a "label" and "value" option.
Array [
label stringrequired
The label option for the filter value.
value stringrequired
The value option for the filter value.
]
filter_var stringrequired
The attribute name by which products will be filtered within this category.
filter_type stringrequired
Possible values: [multiselect, dropdown]
The type of the filter.
filter_range_float
filter_name stringrequired
The name of the filter.
filter_values required
An object that contains the minimum and maximum attribute values allowed by the filter.
min stringrequired
max stringrequired
filter_var stringrequired
The attribute name by which products will be filtered within this category.
filter_type stringrequired
Possible values: [range_float]
The type of the filter.
]
]
status stringrequired
The status of the API request. A value of "OK" indicates that the request was successfully sent and processed.
AddCategoryResponse
status_message stringrequired
status stringrequired
The status of the API request. A value of "OK" indicates that the request was successfully sent and processed.
data objectrequired
id integerrequired
An automatically calculated value that represents a unique PIMS internal category ID.
path stringrequired
The relative path of the category that is calculated and uses '>' as a separator for the category name.
EditCategoryResponse
status_message stringrequired
data objectrequired
name stringrequired
The name of the category identified by category ID
id integerrequired
An automatically calculated value that represents a unique PIMS internal category ID.
cat_order integer
data objectrequired
Metadata associated with the category. Extendable
status string
Describes the activity status of the category. In the context of GET API requests, categories are filtered based on their status, and only categories with the active status will be returned. If the status is not explicitly specified, the category is considered active by default and will be included in the query results.
cat_image string
The path for the image of the category.
cat_rank integer
A numerical classification for the category's rank.
cat_filters object[]
Is an array of filters used to filter data by attribute products in this category, and its structure and number of elements depend on the PIM settings. The following is an example of one possible structure.
Array [
anyOf
filter_dropdown
filter_name stringrequired
The name of the filter.
filter_values object[]required
An array of values for the filter, with each item having a "label" and "value" option.
Array [
label stringrequired
The label option for the filter value.
value stringrequired
The value option for the filter value.
]
filter_var stringrequired
The attribute name by which products will be filtered within this category.
filter_type stringrequired
Possible values: [multiselect, dropdown]
The type of the filter.
filter_range_float
filter_name stringrequired
The name of the filter.
filter_values required
An object that contains the minimum and maximum attribute values allowed by the filter.
min stringrequired
max stringrequired
filter_var stringrequired
The attribute name by which products will be filtered within this category.
filter_type stringrequired
Possible values: [range_float]
The type of the filter.
]
status stringrequired
The status of the API request. A value of "OK" indicates that the request was successfully sent and processed.
Delete Category
status stringrequired
The status of the API request. A value of "OK" indicates that the request was successfully sent and processed.
status_message stringrequired

Example (from schema)

{}

List Categories

{
  "data": [
    {
      "id": 6,
      "cat_name": "Category-1 Name",
      "cat_parent_id": 2,
      "cat_path_id": "2 > 6",
      "cat_path": "Category Name > Category-1 Name",
      "cat_order": 1,
      "data": {
        "status": "active",
        "cat_rank": 1,
        "cat_image": "https://instancename.com/data/category.jpg",
        "cat_filters": [
          {
            "filter_values": {
              "min": "50.00",
              "max": "75.00"
            },
            "filter_var": "price",
            "filter_type": "range_float",
            "filter_name": "Price"
          },
          {
            "filter_var": "brand",
            "filter_type": "multiselect",
            "filter_name": "Brand",
            "filter_values": [
              {
                "value": "Brand Name",
                "label": "Brand Name"
              }
            ]
          }
        ]
      }
    },
    {
      "id": 7,
      "cat_name": "Category-2 Name",
      "cat_parent_id": 2,
      "cat_path_id": "2 > 7",
      "cat_path": "Category Name > Category-2 Name",
      "cat_order": 2,
      "data": {
        "status": "inactive",
        "cat_rank": 10,
        "cat_image": "https://instancename.com/data/category.jpg",
        "cat_filters": [
          {
            "filter_values": {
              "min": "10.00",
              "max": "200.00"
            },
            "filter_var": "price",
            "filter_type": "range_float",
            "filter_name": "Price"
          }
        ]
      }
    }
  ],
  "status": "OK"
}

Add Category

{
  "status_message": "",
  "status": "OK",
  "data": {
    "id": 1000,
    "path": "Parent Name > Child-1 Name > Child-2 Name"
  }
}

Edit Category

{
  "status_message": "",
  "data": {
    "name": "Test",
    "id": 1000,
    "data": {
      "cat_image": "https://instancename.com/data/category.jpg",
      "cat_rank": 12,
      "cat_filters": [
        {
          "filter_type": "range_float",
          "filter_var": "price",
          "filter_values": {
            "min": "18.72",
            "max": "116.38"
          },
          "filter_name": "Price"
        },
        {
          "filter_name": "Brand",
          "filter_var": "brand",
          "filter_type": "multiselect",
          "filter_values": [
            {
              "value": "Brand1",
              "label": "Brand-1"
            },
            {
              "label": "Brand-2",
              "value": "Brand2"
            }
          ]
        }
      ]
    }
  },
  "status": "OK"
}

Delete Category

{
  "status": "OK",
  "status_message": ""
}

default

If there is an error with the API request, additional information will be provided in the response body.
Examples of error messages include:

• addCategory:

  "status_message": "Category with the same name already exists!"

• editCategory:

  If you provided a new name:

  "status_message": "Category with provided name already exists on the same level!" or "New name contains bad characters..."

  If you provided a new path location:

  "status_message": "Parent path does not exist..." or "New path already exist:..."

• deleteCategory:

  "status_message": Category has sub-categories!"

application/json

Schema

Schema

status stringrequired

Possible values: [Error]

The status of the API request. A value of "Error" indicates that the request was not successfully sent or processed.

status_message stringrequired

Provides a message that describes the reason for the error that occurred while processing the API request.

Example (from schema)

{
  "status": "Error",
  "status_message": "string"
}

Loading...