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.
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.
To test the endpoint, open the API reference below or check the example of a curl request.
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.
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.
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.
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.
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.
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.
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.
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.
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?