Category Tutorials

How to create a category

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.

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:

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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
    }
  }'

Last updated

Was this helpful?