Categories
Categories are used to create hierarchical structures within a catalogue.Categories serves as a means for structuring products in meaningful classifications
Categories are used to organize products within catalogues. Categories can be nested in a hierarchy structure of any depth. The catalogue data model defines attributes which can hold data for each category. Attributes can be attached to categories in the master catalogue to define a structure of attributes available to products depending on their category placement in the master catalogue.
GET /v1/categories/ids HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
[
1
]
No more than 5000 categories can be requested at a time. If no limit is provided, the default limit of 1000 will be used
Number of categories to return
1000
Only get categories with id larger than this id
GET /v1/categories HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
{
"Categories": [
{
"Id": 1,
"ParentId": 1,
"SortOrder": 1,
"CatalogueUid": "123e4567-e89b-12d3-a456-426614174000",
"Created": "2025-06-27T08:04:14.753Z",
"CreatedBy": "text",
"LastModified": "2025-06-27T08:04:14.753Z",
"LastModifiedBy": "text",
"HasChildren": true,
"Name": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"Dynamic": true,
"QuerySetup": {
"ProductQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
},
"VariantGroupQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
}
},
"WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
"BusinessUnits": [
{
"AccessPolicy": "text",
"BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
}
]
}
],
"Total": 1,
"Remaining": 1,
"LastId": 1
}
A maximum of 5000 categories can be created in one request
Model for creating a new category
Uid of catalogue to add category to
Id of parent id to place category underneath (set as null, of category shall be at root level of catalogue)
Sort order of category compared to other categories at the same level i the catalogue
Set if products for this category is found by search query set on category
Workflow state to set on the category
POST /v1/categories HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 398
[
{
"CatalogueUid": "123e4567-e89b-12d3-a456-426614174000",
"ParentId": 1,
"SortOrder": 1,
"Dynamic": true,
"QuerySetup": {
"ProductQuery": {
"BooleanOperator": 0
},
"VariantGroupQuery": {
"BooleanOperator": 0
}
},
"WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
"BusinessUnits": [
{
"AccessPolicy": "text",
"BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"Values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
[
1
]
A maximum of 5000 categories can be updated in one request
PATCH /v1/categories HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 425
{
"ANY_ADDITIONAL_PROPERTY": {
"SortOrder": 1,
"MoveCommand": {
"ParentId": 1,
"CatalogueUid": "123e4567-e89b-12d3-a456-426614174000"
},
"QuerySetup": {
"ProductQuery": {
"BooleanOperator": 0
},
"VariantGroupQuery": {
"BooleanOperator": 0
}
},
"WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
"BusinessUnits": [
{
"AccessPolicy": "text",
"BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"Values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
No content
Id of category
GET /v1/categories/{id} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
{
"Id": 1,
"ParentId": 1,
"SortOrder": 1,
"CatalogueUid": "123e4567-e89b-12d3-a456-426614174000",
"Created": "2025-06-27T08:04:14.753Z",
"CreatedBy": "text",
"LastModified": "2025-06-27T08:04:14.753Z",
"LastModifiedBy": "text",
"HasChildren": true,
"Name": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"Dynamic": true,
"QuerySetup": {
"ProductQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
},
"VariantGroupQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
}
},
"WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
"BusinessUnits": [
{
"AccessPolicy": "text",
"BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
}
]
}
Id of category to update
Model representing a category update
Set to update sort order of category compared to other categories at the same level in the catalogue (set as null if you do not want to update this)
Workflow state to set on the category
PATCH /v1/categories/{id} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 397
{
"SortOrder": 1,
"MoveCommand": {
"ParentId": 1,
"CatalogueUid": "123e4567-e89b-12d3-a456-426614174000"
},
"QuerySetup": {
"ProductQuery": {
"BooleanOperator": 0
},
"VariantGroupQuery": {
"BooleanOperator": 0
}
},
"WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
"BusinessUnits": [
{
"AccessPolicy": "text",
"BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"Values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
OK
No content
#Available from v.3.2.0
POST /v1/categories/batch HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3
[
1
]
OK
[
{
"Id": 1,
"ParentId": 1,
"SortOrder": 1,
"CatalogueUid": "123e4567-e89b-12d3-a456-426614174000",
"Created": "2025-06-27T08:04:14.753Z",
"CreatedBy": "text",
"LastModified": "2025-06-27T08:04:14.753Z",
"LastModifiedBy": "text",
"HasChildren": true,
"Name": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"Dynamic": true,
"QuerySetup": {
"ProductQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
},
"VariantGroupQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
}
},
"WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
"BusinessUnits": [
{
"AccessPolicy": "text",
"BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
}
]
}
]
Id of category to get children for
GET /v1/categories/{id}/children HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
[
{
"Id": 1,
"ParentId": 1,
"SortOrder": 1,
"CatalogueUid": "123e4567-e89b-12d3-a456-426614174000",
"Created": "2025-06-27T08:04:14.753Z",
"CreatedBy": "text",
"LastModified": "2025-06-27T08:04:14.753Z",
"LastModifiedBy": "text",
"HasChildren": true,
"Name": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"Dynamic": true,
"QuerySetup": {
"ProductQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
},
"VariantGroupQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
}
},
"WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
"BusinessUnits": [
{
"AccessPolicy": "text",
"BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
}
]
}
]
POST /v1/categories/batch/children HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3
[
1
]
OK
[
{
"Id": 1,
"ParentId": 1,
"SortOrder": 1,
"CatalogueUid": "123e4567-e89b-12d3-a456-426614174000",
"Created": "2025-06-27T08:04:14.753Z",
"CreatedBy": "text",
"LastModified": "2025-06-27T08:04:14.753Z",
"LastModifiedBy": "text",
"HasChildren": true,
"Name": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"Dynamic": true,
"QuerySetup": {
"ProductQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
},
"VariantGroupQuery": {
"BooleanOperator": 0,
"QueryModelType": "text"
}
},
"WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
"BusinessUnits": [
{
"AccessPolicy": "text",
"BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
}
]
}
]
Id of category to get products for
Include archived products
false
GET /v1/categories/{id}/products HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
[
1
]
Wrapper for product children batch query
Category ids to request products for
Indicate whether archibed products shall also be included
POST /v1/categories/batch/products HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 42
{
"CategoryIds": [
1
],
"IncludeArchived": true
}
OK
{
"ANY_ADDITIONAL_PROPERTY": [
1
]
}
Id of category to get product count for
Include archived products in count
false
GET /v1/categories/{id}/products/count HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
1
Wrapper for product children batch query
Category ids to request products for
Indicate whether archibed products shall also be included
POST /v1/categories/batch/products/count HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 42
{
"CategoryIds": [
1
],
"IncludeArchived": true
}
OK
{
"ANY_ADDITIONAL_PROPERTY": 1
}
Use to get a map from an identifier to the internal id of a category in the system. Identifiers are based on attribute values that hold references to external systems. Thus, the identifier can be the id of the category in an external system. You can then use this map to know which category id to update or delete based on the id of the corresponding category in the external system
Alias of identifier type
GET /v1/categories/identifiers/{identifierAlias} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
{
"ANY_ADDITIONAL_PROPERTY": 1
}
Use to get a map from an identifier to the internal id of a category in the system. Identifiers are based on attribute values that hold references to external systems. Thus, the identifier can be the id of the category in an external system. You can then use this map to know which category id to update or delete based on the id of the corresponding category in the external system
Alias of identifier type
Identifier value
GET /v1/categories/identifiers/{identifierAlias}/{identifier} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
1
Use to get a map from an identifier to the internal id of a category in the system. Identifiers are based on attribute values that hold references to external systems. Thus, the identifier can be the id of the category in an external system. You can then use this map to know which category id to update or delete based on the id of the corresponding category in the external system
Provide an identifier alias along with an array of identifiers to get the internal entity ids matching those identifiers
The alias of the identifier
Array of identifiers to return internal ids for
POST /v1/categories/batch/identifiers HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 49
{
"IdentifierAlias": "text",
"Identifiers": [
"text"
]
}
OK
{
"ANY_ADDITIONAL_PROPERTY": 1
}
Id of category
Indicate if only uids of referenced to global list values shall be returned instead of the materialized values
false
GET /v1/categories/{id}/attributevalues HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
{
"CategoryId": 1,
"Values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
Id of category
PATCH /v1/categories/{id}/attributevalues HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 38
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
OK
No content
No more than 5000 categories can be requested at a time.
Define which categories to fetch data for and what data to fetch
Ids of categories to return
Defines which attribute values to return
If IncludeValues is Scopes, define which scopes to return values for here
If IncludeValues is Aliases, define aliases of the attributes to include values for
If IncludeValues is Uids, define uids of the attributes to include values for
Only return values for specific languages
Only return values for specific dimension segments
Indicate if only uids of referenced to global list values shall be returned instead of the materialized values
Get attribute values back in time
POST /v1/categories/batch/attributevalues HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 260
{
"CategoryIds": [
1
],
"IncludeValues": 1,
"Scopes": [
"text"
],
"Aliases": [
"text"
],
"Uids": [
"123e4567-e89b-12d3-a456-426614174000"
],
"LimitToCultureCodes": [
"text"
],
"LimitToSegments": [
"text"
],
"GlobalListValueReferencesOnly": true,
"FromTimestamp": "2025-06-27T08:04:14.753Z"
}
[
{
"CategoryId": 1,
"Values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
A maximum of 5000 categories can be updated in one request
Category attribute values container
Id of category
PATCH /v1/categories/attributevalues HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 66
[
{
"CategoryId": 1,
"Values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
OK
No content
Id of category to get attached attributes from
GET /v1/categories/productattributes HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
[
{
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000",
"CategoryId": 1,
"Owner": 1,
"EditableOnEntities": 0,
"SortOrder": 1
}
]
Id of category to attach attribute to
Uid of attribute to attach
Represents where attributes added to categories are editable on entities placed in that category
Sort order of attribute on category
POST /v1/categories/productattributes HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
No content
Id of category the attribute is attached to
Uid of attached attribute
DELETE /v1/categories/productattributes HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
No content
Id of category the attribute is attached to
Uid of attached attribute
Represents where attributes added to categories are editable on entities placed in that category
Sort order of attribute on category
PATCH /v1/categories/productattributes HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
No content
#Available from v.3.5.0
Id of category
GET /v1/categories/{id}/references HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
{
"CategoryId": 1,
"ReferencingCategories": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingProducts": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingVariantGroups": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingVariants": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingAssets": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingGlobalListValues": [
"123e4567-e89b-12d3-a456-426614174000"
]
}
#Available from v.3.5.0 No more than 5000 values can be requested at a time.
POST /v1/categories/batch/references HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3
[
1
]
OK
[
{
"CategoryId": 1,
"ReferencingCategories": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingProducts": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingVariantGroups": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingVariants": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingAssets": [
{
"EntityId": 1,
"AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
}
],
"ReferencingGlobalListValues": [
"123e4567-e89b-12d3-a456-426614174000"
]
}
]
#Available from v.3.5.0
Id of category to get insights for
GET /v1/categories/{id}/enrichmentinsights HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
[
{
"EnrichmentInsightSetupUid": "123e4567-e89b-12d3-a456-426614174000",
"EntityId": 1,
"Completeness": 1,
"MissingData": [
{
"Type": "text",
"DataReference": "text"
}
],
"Ignored": true
}
]
#Available from v.3.5.0
POST /v1/categories/batch/enrichmentinsights HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3
[
1
]
OK
{
"EnrichmentInsightSetupUid": "123e4567-e89b-12d3-a456-426614174000",
"EntityId": 1,
"Completeness": 1,
"MissingData": [
{
"Type": "text",
"DataReference": "text"
}
],
"Ignored": true
}
#Available from v.3.5.0
Uid of enrichment insight to get for batch of categories
POST /v1/categories/batch/enrichmentinsights/{enrichmentInsightUid} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3
[
1
]
OK
{
"EnrichmentInsightSetupUid": "123e4567-e89b-12d3-a456-426614174000",
"EntityId": 1,
"Completeness": 1,
"MissingData": [
{
"Type": "text",
"DataReference": "text"
}
],
"Ignored": true
}
#Available from v.3.5.0
Id of category
Uid of enrichment insight to toggle ignore for
Indicate whether to ignore the insight for the given enrichment insight and category
PATCH /v1/categories/{id}/enrichmentinsights/{enrichmentInsightSetupUid}/{ignore} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
OK
No content
#Available from v.3.5.0
Uid of enrichment insight to toggle ignore for
Indicate whether to ignore the insight for the given enrichment insight and categories
PATCH /v1/categories/batch/enrichmentinsights/{enrichmentInsightSetupUid}/{ignore} HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3
[
1
]
OK
No content
Search model used for searching products or variants in PIM
Include archived items in result
POST /v1/categories/search HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 59
{
"IncludeArchived": true,
"QueryModel": {
"BooleanOperator": 0
}
}
OK
[
1
]
Get paged result of categories matching certain criteria. Result mapped with headers and item results
Extended search model used for searching products or variants in PIM with support for paging and sorting
Include archived items in result
POST /v1/categories/search/paged HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 148
{
"Page": 1,
"PageSize": 1,
"FieldUids": [
"text"
],
"SortByFieldUid": "text",
"SortDescending": true,
"IncludeArchived": true,
"QueryModel": {
"BooleanOperator": 0
}
}
OK
{
"TotalHits": 1,
"Page": 1,
"PageSize": 1,
"TotalPages": 1,
"ItemListHeaders": [
{
"FieldUid": "text",
"FieldName": "text",
"FieldType": "text",
"SupportsSearching": true,
"SupportsSorting": true
}
],
"ListItems": [
{
"Id": 1,
"ShownValues": [
"text"
]
}
]
}