Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!

Category Tutorial

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 or check the example of a curl request.

API Reference
curl -L 
  --request POST 
  --url 'https://api.emporix.io/category/{tenant}/categories' 
  --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 or check the example of a curl request.

API Reference

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 or check the example of a curl request.

API Reference

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 or check the example of a curl request.

API Reference

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 or check the example of a curl request.

API Reference

How to publish/unpublish a category

To publish or unpublish a category, you need to send a request to the Upserting a category endpoint and set the published property to true or false.

Category tree Retrieving the category trees and Retrieving a specific category tree endpoints exclude trees in which the root category has published=false, when only published categories are requested (showUnpublished=false).

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

API Reference

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 a specific category tree endpoint and provide the category ID in the categoryId path parameter.

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

API Reference

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 or check the example of a curl request.

API Reference

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 or check the example of a curl request.

API Reference

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 Upserting a category endpoint and provide the desired parent category ID in the parentId field.

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

API Reference

Classification

Classification categories allow you to organize products with consistent attributes across your catalog. By defining reusable attribute schemas that are automatically inherited by products assigned to those categories, you can ensure data quality and consistency while reducing manual work.

Creating a classification category

To create a classification category, send a request to the Creating a new category endpoint with the type field set to "CLASSIFICATION" and define ownClassificationMixins.

Response with inherited mixins

When retrieving a classification category that has parent classification categories, the classificationMixins field contains the combined list:

To learn about the end-to-end flow for implementing classification in your B2B commerce platform, along with the product service, see Classification Tutorial.

PreviousCategory ServiceNextClassification Tutorial

Last updated

Was this helpful?