Category Tutorials

How to create a category

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.

The localizedSlug field must not contain any diacritics.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --request POST \
  --url 'https://api.emporix.io/category/{tenant}/categories' \
  --header 'X-Version: v2' \
  --header 'Content-Type: application/json' \
  --data '{
    "parentId": "056bcaf6-66b8-4ddd-9489-65c5f6449e74",
    "localizedName": {
      "en": "Floor Care",
      "de": "Bodenpflege"
    },
    "localizedDescription": {
      "en": "Floor Care",
      "de": "Bodenpflege"
    },
    "localizedSlug": {
      "en": "Floor-Care",
      "de": "Bodenpflege"
    },
    "ecn": [
      "AX6784",
      "123078",
      "SJUIOKM"
    ],
    "validity": {
      "from": "2022-01-05T12:44:51.871Z",
      "to": "2022-12-05T23:59:59.000Z"
    },
    "position": 5,
    "published": true,
    "mixins": {}
  }'

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:

• How to create a category

• How to add your first product

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --request POST \
  --url 'https://api.emporix.io/category/{tenant}/categories/{categoryId}/assignments' \
  --header 'X-Version: v2' \
  --header 'Content-Type: application/json' \
  --data '{
    "ref": {
      "id": "1639265",
      "type": "PRODUCT"
    }
  }'

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --url 'https://api.emporix.io/category/{tenant}/categories/{categoryId}/assignments' \
  --header 'X-Version: v2' \
  --header 'Accept: */*'

How to delete resource assignments

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

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --request DELETE \
  --url 'https://api.emporix.io/category/{tenant}/categories/{categoryId}/assignments' \
  --header 'X-Version: v2' \
  --header 'Accept: */*'

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --request DELETE \
  --url 'https://api.emporix.io/category/{tenant}/categories/{categoryId}/assignments/{assignmentId}' \
  --header 'X-Version: v2' \
  --header 'Accept: */*'

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --request PATCH \
  --url 'https://api.emporix.io/category/{tenant}/categories/{categoryId}' \
  --header 'X-Version: v2' \
  --header 'Content-Type: application/json' \
  --data '{
    "localizedName": {
      "en": "Floor Care Liquids"
    },
    "localizedSlug": {
      "en": "Floor-Care-Liquids"
    },
    "position": 3,
    "published": true,
    "metadata": {
      "version": 1
    }
  }'

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

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --url 'https://api.emporix.io/category/{tenant}/category-trees/{categoryId}' \
  --header 'X-Version: v2' \
  --header 'Accept: */*'

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --url 'https://api.emporix.io/category/{tenant}/category-trees' \
  --header 'X-Version: v2' \
  --header 'Accept: */*'

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.

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --url 'https://api.emporix.io/category/{tenant}/categories/{categoryId}/subcategories' \
  --header 'X-Version: v2' \
  --header 'Accept: */*'

Moving a category

You can move a category by modifying its parentId value.

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.

To test the endpoint, open the API reference below or check the example of a curl request.

API Reference

curl -L \
  --request PATCH \
  --url 'https://api.emporix.io/category/{tenant}/categories/{categoryId}' \
  --header 'X-Version: v2' \
  --header 'Content-Type: application/json' \
  --data '{
    "localizedName": {
      "en": "Floor Care Liquids"
    },
    "localizedSlug": {
      "en": "Floor-Care-Liquids"
    },
    "position": 3,
    "published": true,
    "metadata": {
      "version": 1
    }
  }'