#Categories

Categories are used to create hierarchical structures within a catalogue. Categories serves as a means for structuring products in meaningful classifications

GET /categories Get basic models for categories

No more than 5000 categories can be requested at a time. If no limit is provided, the default limit of 1000 will be used

Request parameters

Property name Parameter type Data type Description
limit query integer

Number of categories to return

afterId query integer

Only get categories with id larger than this id

Response status OK (200)

object : CategoriesResultSet
CategoriesResultSet
Property name Data type Description
Categories array : CategoryModel

List of categories in result set

Total integer

The total number of items

Remaining integer

The remaining items that lie after the last id of the item in this result set

LastId integer

The id of the last item in this result set

CategoryModel
Property name Data type Description
Id integer

Id of category

ParentId integer

Id of category's parent category. Null, if this category is placed in the root of its catalogue

SortOrder integer

Sortorder of the category compared to other categories at the same level in the catalogue

CatalogueUid string

The unique id of the catalogue, this category resides in

Created string

Timestamp of the creation of category

CreatedBy string

Username of user who created this category

LastModified string

Timestamp of last modification of category

LastModifiedBy string

Username of user who did the last modification

HasChildren boolean

Indicates whether this category has any sub categories

Name object

Display name of category (Dictionary of ISO culture code and name)


POST /categories Create new categories

A maximum of 5000 categories can be created in one request

Request parameters

Property name Parameter type Data type Description
categories body array : CreateCategoryModel

Categories

CreateCategoryModel
Property name Data type Description
CatalogueUid string

Uid of catalogue to add category to

ParentId integer

Id of parent id to place category underneath (set as null, of category shall be at root level of catalogue)

SortOrder integer

Sort order of category compared to other categories at the same level i the catalogue

Values object

Dictionary of attribute alias and the corresponding attribute value as an object representation

The table below shows how different attributes translates to this value model.

Attribute type data type
Text attribute string
Number attribute decimal
Boolean attribute bool
Fixedlist attribute value/value[] (depending on whether attribute allows selecting multiple global list values). The datatype of this value model depends on the underlying attribute for the global list of the refernced global list value(s)
Media attribute string/string[] (depending on whether attribute allows selecting multiple medias)
Datetime attribute DateTimeOffset
Category attribute int/int[] (depending on whether attribute allows selecting multiple categories)
Product attribute int/int[] (depending on whether attribute allows selecting multiple products)
Variant attribute int/int[] (depending on whether attribute allows selecting multiple variants)
Collection attribute uuid/uuid[] (depending on whether attribute allows selecting multiple collections)
Attribute attribute string/string[] (depending on whether attribute allows selecting multiple attributes)
Complex attribute object (Each property of the object corresponds to each sub attribute of the complex attribute. The value of each property then corresponds to the data type of that sub attribute)
List attribute value[] (Each value in the array represents each row in the list. The model of each row corresponds to the datatype of the row template set up on the list attribute)

Response status OK (200)

array : integer

DELETE /categories Delete multiple categories

Request parameters

Property name Parameter type Data type Description
categoryIds body array : integer

Delete model

Response status OK (200)

No body message is returned

PATCH /categories Update multiple categories

A maximum of 5000 categories can be updated in one request

Request parameters

Property name Parameter type Data type Description
categories body object

Update model

Response status OK (200)

No body message is returned

GET /categories/{id} Get basic model for a category

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category

Response status OK (200)

object : CategoryModel
CategoryModel
Property name Data type Description
Id integer

Id of category

ParentId integer

Id of category's parent category. Null, if this category is placed in the root of its catalogue

SortOrder integer

Sortorder of the category compared to other categories at the same level in the catalogue

CatalogueUid string

The unique id of the catalogue, this category resides in

Created string

Timestamp of the creation of category

CreatedBy string

Username of user who created this category

LastModified string

Timestamp of last modification of category

LastModifiedBy string

Username of user who did the last modification

HasChildren boolean

Indicates whether this category has any sub categories

Name object

Display name of category (Dictionary of ISO culture code and name)


DELETE /categories/{id} Delete a category

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category to delete

Response status OK (200)

No body message is returned

PATCH /categories/{id} Update category

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category to update

model body object : UpdateCategoryModel

Update model

UpdateCategoryModel
Property name Data type Description
SortOrder integer

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)

MoveCommand object : CategoryMoveModel

Set to update the categorys placement in a catalogue (set as null if you do not want to update this)

#Available from 3.8.0

Values object

Dictionary of attribute alias and the corresponding attribute value as an object representation

The table below shows how different attributes translates to this value model.

Attribute type data type
Text attribute string
Number attribute decimal
Boolean attribute bool
Fixedlist attribute value/value[] (depending on whether attribute allows selecting multiple global list values). The datatype of this value model depends on the underlying attribute for the global list of the refernced global list value(s)
Media attribute string/string[] (depending on whether attribute allows selecting multiple medias)
Datetime attribute DateTimeOffset
Category attribute int/int[] (depending on whether attribute allows selecting multiple categories)
Product attribute int/int[] (depending on whether attribute allows selecting multiple products)
Variant attribute int/int[] (depending on whether attribute allows selecting multiple variants)
Collection attribute uuid/uuid[] (depending on whether attribute allows selecting multiple collections)
Attribute attribute string/string[] (depending on whether attribute allows selecting multiple attributes)
Complex attribute object (Each property of the object corresponds to each sub attribute of the complex attribute. The value of each property then corresponds to the data type of that sub attribute)
List attribute value[] (Each value in the array represents each row in the list. The model of each row corresponds to the datatype of the row template set up on the list attribute)
CategoryMoveModel
Property name Data type Description
ParentId integer

New parent id of category

CatalogueUid string

New catalogue uid of category

Response status OK (200)

No body message is returned

GET /categories/{id}/attributevalues Get attribute values for the category

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category

globalListValueReferencesOnly query boolean

Indicate if only uids of referenced to global list values shall be returned instead of the materialized values

Response status OK (200)

object : CategoryAttributeValuesModel
CategoryAttributeValuesModel
Property name Data type Description
CategoryId integer

Id of category

Values object

Dictionary of attribute alias and the corresponding attribute value as an object representation

The table below shows how different attributes translates to this value model.

Attribute type data type
Text attribute string
Number attribute decimal
Boolean attribute bool
Fixedlist attribute value/value[] (depending on whether attribute allows selecting multiple global list values). The datatype of this value model depends on the underlying attribute for the global list of the refernced global list value(s)
Media attribute string/string[] (depending on whether attribute allows selecting multiple medias)
Datetime attribute DateTimeOffset
Category attribute int/int[] (depending on whether attribute allows selecting multiple categories)
Product attribute int/int[] (depending on whether attribute allows selecting multiple products)
Variant attribute int/int[] (depending on whether attribute allows selecting multiple variants)
Collection attribute uuid/uuid[] (depending on whether attribute allows selecting multiple collections)
Attribute attribute string/string[] (depending on whether attribute allows selecting multiple attributes)
Complex attribute object (Each property of the object corresponds to each sub attribute of the complex attribute. The value of each property then corresponds to the data type of that sub attribute)
List attribute value[] (Each value in the array represents each row in the list. The model of each row corresponds to the datatype of the row template set up on the list attribute)

PATCH /categories/{id}/attributevalues

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category

values body object

Dictionary of attribute values to update

Response status OK (200)

No body message is returned

GET /categories/{id}/children Get child categories of a specific category

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category to get children for

Response status OK (200)

array : CategoryModel
CategoryModel
Property name Data type Description
Id integer

Id of category

ParentId integer

Id of category's parent category. Null, if this category is placed in the root of its catalogue

SortOrder integer

Sortorder of the category compared to other categories at the same level in the catalogue

CatalogueUid string

The unique id of the catalogue, this category resides in

Created string

Timestamp of the creation of category

CreatedBy string

Username of user who created this category

LastModified string

Timestamp of last modification of category

LastModifiedBy string

Username of user who did the last modification

HasChildren boolean

Indicates whether this category has any sub categories

Name object

Display name of category (Dictionary of ISO culture code and name)


GET /categories/{id}/enrichmentinsights Get Enrichment Insights for a category

#Available from v.3.5.0

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category to get insights for

Response status OK (200)

array : EntityEnrichmentInsight
EntityEnrichmentInsight
Property name Data type Description
EnrichmentInsightSetupUid string

Uid of enrichment insight

EntityId integer

Id of entity

Completeness integer

Completeness in percentage (0 - 100). Is null, if ignored is true

MissingData array : InsightDataReference

List of missing data for this entity to reach 100% completeness for this enrichment insight

Ignored boolean

Indicates whether the completeness is ignored for this entity and this enrichment insight

InsightDataReference
Property name Data type Description
Type string

Type of data reference

DataReference string

The data reference itself


PATCH /categories/{id}/enrichmentinsights/{enrichmentInsightSetupUid}/{ignore} Enable or disable an enrichment insight for a category

#Available from v.3.5.0

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category

enrichmentInsightSetupUid path string

Uid of enrichment insight to toggle ignore for

ignore path boolean

Indicate whether to ignore the insight for the given enrichment insight and category

Response status OK (200)

No body message is returned

GET /categories/{id}/products Get ids of products in a category

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category to get products for

includeArchived query boolean

Include archived products

Response status OK (200)

array : integer

GET /categories/{id}/products/count Get the number of products in a category

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category to get product count for

includeArchived query boolean

Include archived products in count

Response status OK (200)

integer

GET /categories/{id}/references Get references to a category

#Available from v.3.5.0

Request parameters

Property name Parameter type Data type Description
id path integer

Id of category

Response status OK (200)

object : CategoryReferences
CategoryReferences
Property name Data type Description
CategoryId integer

Id of the referenced category

ReferencingCategories array : EntityReferenceDetail

List of categories referencing this category

ReferencingProducts array : EntityReferenceDetail

List of products referencing this category

ReferencingVariants array : EntityReferenceDetail

List of variants referencing this category

ReferencingGlobalListValues array

List of global list values referencing this category

EntityReferenceDetail
Property name Data type Description
EntityId integer

The id of the referencing entity

AttributeUid string

The attribute on the referencing entity that holds the reference


PATCH /categories/attributevalues Update attribute values on multiple categories

A maximum of 5000 categories can be updated in one request

Request parameters

Property name Parameter type Data type Description
model body array : CategoryAttributeValuesModel

Update model

CategoryAttributeValuesModel
Property name Data type Description
CategoryId integer

Id of category

Values object

Dictionary of attribute alias and the corresponding attribute value as an object representation

The table below shows how different attributes translates to this value model.

Attribute type data type
Text attribute string
Number attribute decimal
Boolean attribute bool
Fixedlist attribute value/value[] (depending on whether attribute allows selecting multiple global list values). The datatype of this value model depends on the underlying attribute for the global list of the refernced global list value(s)
Media attribute string/string[] (depending on whether attribute allows selecting multiple medias)
Datetime attribute DateTimeOffset
Category attribute int/int[] (depending on whether attribute allows selecting multiple categories)
Product attribute int/int[] (depending on whether attribute allows selecting multiple products)
Variant attribute int/int[] (depending on whether attribute allows selecting multiple variants)
Collection attribute uuid/uuid[] (depending on whether attribute allows selecting multiple collections)
Attribute attribute string/string[] (depending on whether attribute allows selecting multiple attributes)
Complex attribute object (Each property of the object corresponds to each sub attribute of the complex attribute. The value of each property then corresponds to the data type of that sub attribute)
List attribute value[] (Each value in the array represents each row in the list. The model of each row corresponds to the datatype of the row template set up on the list attribute)

Response status OK (200)

No body message is returned

POST /categories/batch Get basic model for a batch of categories

#Available from v.3.2.0

Request parameters

Property name Parameter type Data type Description
categoryIds body array : integer

Ids of categories to return

Response status OK (200)

array : CategoryModel
CategoryModel
Property name Data type Description
Id integer

Id of category

ParentId integer

Id of category's parent category. Null, if this category is placed in the root of its catalogue

SortOrder integer

Sortorder of the category compared to other categories at the same level in the catalogue

CatalogueUid string

The unique id of the catalogue, this category resides in

Created string

Timestamp of the creation of category

CreatedBy string

Username of user who created this category

LastModified string

Timestamp of last modification of category

LastModifiedBy string

Username of user who did the last modification

HasChildren boolean

Indicates whether this category has any sub categories

Name object

Display name of category (Dictionary of ISO culture code and name)


POST /categories/batch/attributevalues Get attribute values for multiple categories

No more than 5000 categories can be requested at a time.

Request parameters

Property name Parameter type Data type Description
model body object : CategoryValueRequestModel

Request model

CategoryValueRequestModel
Property name Data type Description
CategoryIds array

Ids of categories to return

IncludeValues string

Select if any source of values shall be returned

Scopes array

If IncludeValues is Scopes, define which scopes to return values for here

Aliases array

If IncludeValues is Aliases, define aliases of the attributes to include values for

Uids array

If IncludeValues is Uids, define uids of the attributes to include values for

LimitToCultureCodes array

Only return values for specific languages

LimitToSegments array

Only return values for specific dimension segments

GlobalListValueReferencesOnly boolean

Indicate if only uids of referenced to global list values shall be returned instead of the materialized values

FromTimestamp string

Get attribute values back in time

Response status OK (200)

array : CategoryAttributeValuesModel
CategoryAttributeValuesModel
Property name Data type Description
CategoryId integer

Id of category

Values object

Dictionary of attribute alias and the corresponding attribute value as an object representation

The table below shows how different attributes translates to this value model.

Attribute type data type
Text attribute string
Number attribute decimal
Boolean attribute bool
Fixedlist attribute value/value[] (depending on whether attribute allows selecting multiple global list values). The datatype of this value model depends on the underlying attribute for the global list of the refernced global list value(s)
Media attribute string/string[] (depending on whether attribute allows selecting multiple medias)
Datetime attribute DateTimeOffset
Category attribute int/int[] (depending on whether attribute allows selecting multiple categories)
Product attribute int/int[] (depending on whether attribute allows selecting multiple products)
Variant attribute int/int[] (depending on whether attribute allows selecting multiple variants)
Collection attribute uuid/uuid[] (depending on whether attribute allows selecting multiple collections)
Attribute attribute string/string[] (depending on whether attribute allows selecting multiple attributes)
Complex attribute object (Each property of the object corresponds to each sub attribute of the complex attribute. The value of each property then corresponds to the data type of that sub attribute)
List attribute value[] (Each value in the array represents each row in the list. The model of each row corresponds to the datatype of the row template set up on the list attribute)

POST /categories/batch/children Get child categories for a range categories

Request parameters

Property name Parameter type Data type Description
categoryIds body array : integer

Response status OK (200)

array : CategoryModel
CategoryModel
Property name Data type Description
Id integer

Id of category

ParentId integer

Id of category's parent category. Null, if this category is placed in the root of its catalogue

SortOrder integer

Sortorder of the category compared to other categories at the same level in the catalogue

CatalogueUid string

The unique id of the catalogue, this category resides in

Created string

Timestamp of the creation of category

CreatedBy string

Username of user who created this category

LastModified string

Timestamp of last modification of category

LastModifiedBy string

Username of user who did the last modification

HasChildren boolean

Indicates whether this category has any sub categories

Name object

Display name of category (Dictionary of ISO culture code and name)


POST /categories/batch/enrichmentinsights Get Enrichment Insights for a batch of categories

#Available from v.3.5.0

Request parameters

Property name Parameter type Data type Description
categoryIds body array : integer

Ids of categories to get insights for

Response status OK (200)

array : EntityEnrichmentInsight
EntityEnrichmentInsight
Property name Data type Description
EnrichmentInsightSetupUid string

Uid of enrichment insight

EntityId integer

Id of entity

Completeness integer

Completeness in percentage (0 - 100). Is null, if ignored is true

MissingData array : InsightDataReference

List of missing data for this entity to reach 100% completeness for this enrichment insight

Ignored boolean

Indicates whether the completeness is ignored for this entity and this enrichment insight

InsightDataReference
Property name Data type Description
Type string

Type of data reference

DataReference string

The data reference itself


PATCH /categories/batch/enrichmentinsights/{enrichmentInsightSetupUid}/{ignore} Enable or disable an enrichment insight for a batch of categories

#Available from v.3.5.0

Request parameters

Property name Parameter type Data type Description
categoryIds body array : integer

Ids of categories to toggle ignore for

enrichmentInsightSetupUid path string

Uid of enrichment insight to toggle ignore for

ignore path boolean

Indicate whether to ignore the insight for the given enrichment insight and categories

Response status OK (200)

No body message is returned

POST /categories/batch/enrichmentinsights/{enrichmentInsightUid} Get insights for a batch of categories and a specific Enrichment Insight

#Available from v.3.5.0

Request parameters

Property name Parameter type Data type Description
categoryIds body array : integer

Ids of categories to get insights for

enrichmentInsightUid path string

Uid of enrichment insight to get for batch of categories

Response status OK (200)

array : EntityEnrichmentInsight
EntityEnrichmentInsight
Property name Data type Description
EnrichmentInsightSetupUid string

Uid of enrichment insight

EntityId integer

Id of entity

Completeness integer

Completeness in percentage (0 - 100). Is null, if ignored is true

MissingData array : InsightDataReference

List of missing data for this entity to reach 100% completeness for this enrichment insight

Ignored boolean

Indicates whether the completeness is ignored for this entity and this enrichment insight

InsightDataReference
Property name Data type Description
Type string

Type of data reference

DataReference string

The data reference itself


POST /categories/batch/identifiers Get internal ids of multiple categories from their identifier

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

Request parameters

Property name Parameter type Data type Description
model body object : IdentifierBatchModel

Specify alias of identifier type and the identifiers to return internal ids for

IdentifierBatchModel
Property name Data type Description
IdentifierAlias string

The alias of the identifier

Identifiers array

Array of identifiers to return internal ids for

Response status OK (200)

object

POST /categories/batch/products Get ids of products in a categories

Request parameters

Property name Parameter type Data type Description
model body object : CategoryProductsModel
CategoryProductsModel
Property name Data type Description
CategoryIds array

Category ids to request products for

IncludeArchived boolean

Indicate whether archibed products shall also be included

Response status OK (200)

object

POST /categories/batch/products/count Get the number of products in a batch of categories

Request parameters

Property name Parameter type Data type Description
model body object : CategoryProductsModel

Categories to get number of products for

CategoryProductsModel
Property name Data type Description
CategoryIds array

Category ids to request products for

IncludeArchived boolean

Indicate whether archibed products shall also be included

Response status OK (200)

object

POST /categories/batch/references Get references to a batch of categories

#Available from v.3.5.0 No more than 5000 values can be requested at a time.

Request parameters

Property name Parameter type Data type Description
ids body array : integer

Ids of categories

Response status OK (200)

array : CategoryReferences
CategoryReferences
Property name Data type Description
CategoryId integer

Id of the referenced category

ReferencingCategories array : EntityReferenceDetail

List of categories referencing this category

ReferencingProducts array : EntityReferenceDetail

List of products referencing this category

ReferencingVariants array : EntityReferenceDetail

List of variants referencing this category

ReferencingGlobalListValues array

List of global list values referencing this category

EntityReferenceDetail
Property name Data type Description
EntityId integer

The id of the referencing entity

AttributeUid string

The attribute on the referencing entity that holds the reference


GET /categories/identifiers/{identifierAlias} Get all identifiers and their internal ids for a specific identifier type

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

Request parameters

Property name Parameter type Data type Description
identifierAlias path string

Alias of identifier type

Response status OK (200)

object

GET /categories/identifiers/{identifierAlias}/{identifier} Get the internal id of a category based on its identifier

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

Request parameters

Property name Parameter type Data type Description
identifierAlias path string

Alias of identifier type

identifier path string

Identifier value

Response status OK (200)

integer

GET /categories/ids Get ids of all categories in the system

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.

Response status OK (200)

array : integer

GET /categories/productattributes Get product attributes on category

Request parameters

Property name Parameter type Data type Description
categoryId query integer

Id of category to get attached attributes from

Response status OK (200)

No body message is returned

POST /categories/productattributes Attach attribute to a category, which is to be visible to products in that category

Request parameters

Property name Parameter type Data type Description
categoryId query integer

Id of category to attach attribute to

attributeUid query string

Uid of attribute to attach

editableOnEntities query string

Editable on product and/or variant

Response status OK (200)

No body message is returned

DELETE /categories/productattributes Remove a product attribute from a category

Request parameters

Property name Parameter type Data type Description
categoryId query integer

Id of category the attribute is attached to

attributeUid query string

Uid of attached attribute

Response status OK (200)

No body message is returned

PATCH /categories/productattributes Update attribute on a category

Request parameters

Property name Parameter type Data type Description
categoryId query integer

Id of category the attribute is attached to

attributeUid query string

Uid of attached attribute

editableOnEntities query string

Editable on product and/or variant

Response status OK (200)

No body message is returned