POST /MerchandiseCategories

GENERAL INFORMATION

Purpose

This endpoint is used for sharing product merchandise category information, which defines types of products.

How the data is used

We map each customer’s unique merchandise categories to an industry-standard taxonomy so our AI model can correctly understand the product type. We do this across all customers, allowing the pooled model to learn from every product of every customer to improve the accuracy of the predictions. Not having a merchandise category on a product means we cannot deliver a prediction for that product.

This merchandise category is also allows the business to apply business rules and automation on these categories in our customer portal.

This makes it a mandatory dataset.

Best practices

1. Make sure to update the merchandise categories are updated on a regular basis, recommended minimum once a day, to ensure the new categories to be created in the customer portal to be mapped to the industry standard to enable predictions for the products assigned to this merchandise category.

2. Ensure that the id you are using in this endpoint aligns with the merchandiseCategoryId you are assigning to the items in this endpoint POST /Items

3. Always align with the business on the desired structures of the merchandise category hierarchy, but what we typically see as industry standard is a hierarchical structure with multiple levels:

   a. Top level > contains the genders / target audiences e.g. Women, Men, Boys, Girls (if applicable)

   b. Mid level > contains the main product group e.g. T-Shirt, Dress

   c. Bottom level > contains the product subgroup e.g. T-Shirt Long Sleeve, T-Shirt Short Sleeve, Dress Maxi, Dress Formal

   For multi brand retailers it is also common to have an additional level for the brand, either on the highest level or under the top level. To allow you to also implement this hierarchical structure we ask for a parentCategoryId for each merchandise category, so you are able to nest categories under other categories, creating this hierarchical structure. See example json below.

4. We always recommend including the gender/target audience (if applicable) on the description of the bottom level categories. This allows users in our portal to quickly see if they are looking at a men’s or women’s T-Shirt category for example.

Common pitfalls

1. Never use a randomly generated uuid for the merchandiseCategoryId field, as you need this to also be able to be able to update the merchandise category information.

2. A common pitfall is to send a system generated like a uuid in the code field, which can make it unclear for users in our customer portal to see which merchandise category they are looking at.

3. Forgetting to implement the parentMerchandiseCategoryId, or using a different id structure for the parentMerchandiseCategoryId as you use for the merchandiseCategoryId , resulting in a non-hierarchical structure while the business expects it to be hierarchical.

Example use cases

1. As a merchandiser I want to enable Wallie to do the automated replenishment for all Men’s Short Sleeved T-Shirt.

2. As a buyer I want to be able to filter the overviews on the products in the category that I am responsible for.

3. As a merchandiser I want to hide all the products in the customer portal which are nested under the “Other” category as we do not apply any business rules on it, nor do any replenishment/redistribution/intitial distribution on these products.

TECHNICAL INFORMATION

Authentication

Bearer token, information on page POST /Token

Headers

QueryParameters:

Body example:

{
  "merchandiseCategories": [
    {
      "merchandiseCategoryId": "1",
      "code": "1",
      "description": "Women",
      "merchandiseCategoryLevelId": "1"
    },
    {
      "merchandiseCategoryId": "10",
      "code": "10",
      "description": "Women T-Shirts",
      "parentMerchandiseCategoryId": "1",
      "merchandiseCategoryLevelId": "1"
    },
    {
      "merchandiseCategoryId": "1000",
      "code": "1000",
      "description": "Women T-Shirts Short Sleeve",
      "parentMerchandiseCategoryId": "10",
      "merchandiseCategoryLevelId": "1"
    },
    {
      "merchandiseCategoryId": "2",
      "code": "2",
      "description": "Men",,
      "merchandiseCategoryLevelId": "1"
    },
    {
      "merchandiseCategoryId": "20",
      "code": "20",
      "description": "Men T-Shirts",
      "parentMerchandiseCategoryId": "2",
      "merchandiseCategoryLevelId": "1"
    },
    {
      "merchandiseCategoryId": "2000",
      "code": "2000",
      "description": "Men T-Shirts Short Sleeve",
      "parentMerchandiseCategoryId": "20",
      "merchandiseCategoryLevelId": "1"
    }
  ]
}

Field information:

RESPONSE

StatusCodes:

200 = OK

401 = Unauthorized, which means an expired/missing/invalid token

400 = Bad request, see body of the response to check which validation errors have occured

500 = System error, see body of the response to check which error has occured or contact integration support

Body Example:

No body in the response