Categories help organize your Products into various classifications. Customers can navigate a shop by browsing for related Products based on each Category.
Products can belong to multiple Categories, and there can be different Category hierarchies for various purposes and Channels. Categories are embedded in the Product search, enabling you to filter and search for Products by their respective parent and child Categories. You can create Categories and customize existing ones based on your specific content, workflows, and metadata requirements.
Categories include built-in fields for search engine optimization, such as unique and internationalizable URL slugs. Because slugs are an API resource for each Category, they can handle large quantities of Categories. The Merchant Center is also designed to handle these classifications of Categories.
Representations
Category
id ​String​ | Unique identifier of the Category. |
version ​Int​ | Current version of the Category. |
key ​String​ | User-defined unique identifier of the Category. MinLength:Â2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
externalId ​String​ | Additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP). |
name ​ | Name of the Category. |
slug ​ | User-defined identifier used as a deep-link URL to the related Category per Locale.
A Category can have the same slug for different Locales, but they are unique across the Project.
Valid slugs match the pattern ^[A-Za-z0-9_-]{2,256}+$ .
For good performance, indexes are provided for the first 15 languages set in a Project. |
description ​ | Description of the Category. |
ancestors ​Array of CategoryReference​ | Contains the parent path towards the root Category. |
parent ​ | Parent Category of this Category. |
orderHint ​String​ | Decimal value between 0 and 1. Frontend applications can use this value for ordering Categories within the same level in the category tree. |
metaTitle ​ | Name of the Category used by external search engines for improved search engine performance. |
metaDescription ​ | Description of the Category used by external search engines for improved search engine performance. |
metaKeywords ​ | Keywords related to the Category for improved search engine performance. |
assets ​Array of Asset​ | Media related to the Category. |
custom ​CustomFields​ | Custom Fields for the Category. |
createdAt ​DateTime​ | Date and time (UTC) the Category was initially created. |
createdBy ​BETACreatedBy​ | IDs and references that created the Category. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the Category was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified the Category. |
CategoryDraft
key ​String​ | User-defined unique identifier for the Category. This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing Categories with the Import API and the Merchant Center. MinLength: 2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
externalId ​String​ | Additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP). |
name ​ | Name of the Category. |
slug ​ | |
description ​ | Description of the Category. |
parent ​ | Parent Category of the Category.
The parent can be set by its id or key . |
orderHint ​String​ | Decimal value between 0 and 1. Frontend applications can use this value for ordering Categories within the same level in the category tree. If not set, a random value will be assigned. |
metaTitle ​ | Name of the Category used by external search engines for improved search engine performance. |
metaDescription ​ | Description of the Category used by external search engines for improved search engine performance. |
metaKeywords ​ | Keywords related to the Category for improved search engine performance. |
assets ​Array of AssetDraft​ | Media related to the Category. |
custom ​ | Custom Fields for the Category. |
CategoryPagedQueryResponse
limit ​Int​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset ​Int​ | Number of elements skipped. Default: 0 ​Maximum: 10000 ​ |
count ​Int​ | Actual number of results returned. |
total ​Int​ | Total number of results matching the query.
This number is an estimation that is not strongly consistent.
This field is returned by default.
For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false .
When the results are filtered with a Query Predicate, total is subject to a limit. |
results ​Array of Category​ | Category matching the query. |
CategoryReference
id ​String​ | Unique identifier of the referenced Category. |
typeId ​ | category Type of referenced resource. |
obj ​Category​ | Contains the representation of the expanded Category. Only present in responses to requests with Reference Expansion for Categories. |
CategoryResourceIdentifier
id
or key
is required. If both are set, an InvalidJsonInput error is returned.id ​String​ | Unique identifier of the referenced Category. Required if key is absent. |
key ​String​ | User-defined unique identifier of the referenced Category. Required if id is absent. |
typeId ​ | category Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
Get Category
Get Category by ID
view_products:{projectKey}
view_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the Category. |
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
"version": 1,
"name": {
"en": "Hats"
},
"slug": {
"en": "hats"
},
"parent": {
"typeId": "category",
"id": "123456"
},
"ancestors": [],
"orderHint": "0.1",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
Get Category by Key
view_products:{projectKey}
view_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the Category. |
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/categories/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
"version": 1,
"name": {
"en": "Hats"
},
"slug": {
"en": "hats"
},
"parent": {
"typeId": "category",
"id": "123456"
},
"ancestors": [],
"orderHint": "0.1",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
Query Categories
view_products:{projectKey}
view_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int ​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset Int ​ | Number of elements skipped. Default: 0 ​Maximum: 10000 ​ |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.Default: true ​ |
var.<varName> String ​ | Predicate parameter values. The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/categories -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
"version": 1,
"name": {
"en": "Hats"
},
"slug": {
"en": "hats"
},
"ancestors": [
{
"typeId": "category",
"id": "123456"
}
],
"orderHint": "0.1",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
},
{
"id": "1bae3aa3-1e02-49d2-b719-4c5020f50638",
"version": 1,
"name": {
"en": "Long sleeves"
},
"slug": {
"en": "long-sleeves"
},
"ancestors": [],
"orderHint": "0.2",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
]
}
Check if Category exists
Check if Category exists by ID
id
. Returns a 200 OK
status if the Category exists or a 404 Not Found
otherwise.view_products:{projectKey}
view_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the Category. |
curl --head https://api.{region}.commercetools.com/{projectKey}/categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Category exists by Key
key
. Returns a 200 OK
status if the Category exists or a 404 Not Found
otherwise.view_products:{projectKey}
view_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the Category. |
curl --head https://api.{region}.commercetools.com/{projectKey}/categories/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Category exists by Query Predicate
200 OK
status if any Categories match the query predicate, or a 404 Not Found
otherwise.view_products:{projectKey}
view_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/categories -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create Category
manage_products:{projectKey}
manage_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/categories -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"name" : {
"en" : "Hats"
},
"slug" : {
"en" : "hats"
},
"parent" : {
"typeId" : "category",
"id" : "123456"
},
"orderHint" : "0.1"
}
DATA
{
"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
"version": 1,
"name": {
"en": "Hats"
},
"slug": {
"en": "hats"
},
"parent": {
"typeId": "category",
"id": "123456"
},
"ancestors": [],
"orderHint": "0.1",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
Update Category
Update Category by ID
manage_products:{projectKey}
manage_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the Category. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the Category on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions ​Array of CategoryUpdateAction​ | Update actions to be performed on the Category. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeName",
"name" : {
"en" : "New Name"
}
} ]
}
DATA
{
"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
"version": 1,
"name": {
"en": "Hats"
},
"slug": {
"en": "hats"
},
"parent": {
"typeId": "category",
"id": "123456"
},
"ancestors": [],
"orderHint": "0.1",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
Update Category by Key
manage_products:{projectKey}
manage_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the Category. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the Category on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions ​Array of CategoryUpdateAction​ | Update actions to be performed on the Category. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/categories/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeName",
"name" : {
"en" : "New Name"
}
} ]
}
DATA
{
"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
"version": 1,
"name": {
"en": "Hats"
},
"slug": {
"en": "hats"
},
"parent": {
"typeId": "category",
"id": "123456"
},
"ancestors": [],
"orderHint": "0.1",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
Update actions
Set Key
action ​String​ | "setKey" |
key ​String​ | Value to set. If empty, any existing value will be removed. MinLength:Â2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
{
"action": "setKey",
"key": "myNewKey"
}
Change Name
action ​String​ | "changeName" |
name ​ | New value to set. Must not be empty. |
{
"action": "changeName",
"name": {
"de": "neuer Category Name",
"en": "new category name"
}
}
Change Slug
action ​String​ | "changeSlug" |
slug ​ |
{
"action": "changeSlug",
"slug": {
"de": "meine-kategorie",
"en": "my-category"
}
}
Set Description
action ​String​ | "setDescription" |
description ​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setDescription",
"description": {
"de": "This is a category description",
"en": "Dies ist eine Kategorie-Beschreibung"
}
}
Change Parent
Changing parents should not be done concurrently. Concurrent changes of parent categories might lead to corrupted ancestor lists (paths).
action ​String​ | "changeParent" |
parent ​ | New value to set as parent. |
{
"action": "changeParent",
"parent": {
"typeId": "category",
"id": "{{category-id}}"
}
}
Change OrderHint
action ​String​ | "changeOrderHint" |
orderHint ​String​ | New value to set. Must be a decimal value between 0 and 1. |
{
"action": "changeOrderHint",
"orderHint": "0.1"
}
Set External ID
This update action sets a new ID that can be used as an additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP).
action ​String​ | "setExternalId" |
externalId ​String​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setExternalId",
"externalId": "externalIdString"
}
Set Meta Title
action ​String​ | "setMetaTitle" |
metaTitle ​ | Value to set. |
{
"action": "setMetaTitle",
"metaTitle": {
"de": "Dies ist mein Meta-Title",
"en": "This is my meta title"
}
}
Set Meta Description
action ​String​ | "setMetaDescription" |
metaDescription ​ | Value to set. |
{
"action": "setMetaDescription",
"metaDescription": {
"de": "Dies ist meine MetaDecription",
"en": "this is my meta description"
}
}
Set Meta Keywords
action ​String​ | "setMetaKeywords" |
metaKeywords ​ | Value to set. |
{
"action": "setMetaKeywords",
"metaKeywords": {
"de": "commercetools, genial",
"en": "commercetools, aweseome"
}
}
Set Custom Type
action ​String​ | "setCustomType" |
type ​ | Defines the Type that extends the Category with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the Category. |
fields ​ | Sets the Custom Fields fields for the Category. |
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}
Set CustomField
action ​String​ | "setCustomField" |
name ​String​ | Name of the Custom Field. |
value ​ | If value is absent or null , this field will be removed if it exists.
Removing a field that does not exist returns an InvalidOperation error.
If value is provided, it is set for the field defined by name . |
{
"action": "setCustomField",
"name": "exampleStringField",
"value": "TextString"
}
Add Asset
action ​String​ | "addAsset" |
asset ​AssetDraft​ | Value to append. |
position ​Int​ | Position in the array at which the Asset should be put. When specified, the value must be between 0 and the total number of Assets minus 1 . |
{
"action": "addAsset",
"asset": {
"sources": [
{
"uri": "https://www.commercetools.de/ct-logo.svg",
"key": "vector"
}
],
"name": {
"de": "commercetools Logo",
"en": "commercetools logo"
}
}
}
Remove Asset
action ​String​ | "removeAsset" |
assetId ​String​ | Value to remove. Either assetId or assetKey is required. |
assetKey ​String​ | Value to remove. Either assetId or assetKey is required. |
{
"action": "removeAsset",
"assetId": "{{assetId}}"
}
Set Asset Key
key
of an Asset.action ​String​ | "setAssetKey" |
assetId ​String​ | Value to set. |
assetKey ​String​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setAssetKey",
"assetId": "{{assetId}}"
}
Change Asset Order
assets
array. The new order is defined by listing the id
s of the Assets.action ​String​ | "changeAssetOrder" |
assetOrder ​Array of String​ | New value to set. Must contain all Asset id s. |
{
"action": "changeAssetOrder",
"assetOrder": [
"{{assetId1}}",
"{{assetId2}}"
]
}
Change Asset Name
action ​String​ | "changeAssetName" |
assetId ​String​ | New value to set. Either assetId or assetKey is required. |
assetKey ​String​ | New value to set. Either assetId or assetKey is required. |
name ​ | New value to set. Must not be empty. |
{
"action": "changeAssetName",
"assetId": "{{assetId}}",
"name": {
"de": "Mein Asset",
"en": "My asset"
}
}
Set Asset Description
action ​String​ | "setAssetDescription" |
assetId ​String​ | New value to set. Either assetId or assetKey is required. |
assetKey ​String​ | New value to set. Either assetId or assetKey is required. |
description ​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setAssetDescription",
"assetId": "{{assetId}}",
"description": {
"de": "Dies ist eine Asset-Beschreibung",
"en": "This is an asset description"
}
}
Set Asset Sources
action ​String​ | "setAssetSources" |
assetId ​String​ | New value to set. Either assetId or assetKey is required. |
assetKey ​String​ | New value to set. Either assetId or assetKey is required. |
sources ​Array of AssetSource​ | Must not be empty. At least one entry is required. |
{
"action": "setAssetSources",
"assetId": "{{assetId}}",
"sources": [
{
"uri": "https://www.commercetools.de/ct-logo.svg",
"key": "vector"
}
]
}
Set Asset Custom Type
action ​String​ | "setAssetCustomType" |
assetId ​String​ | New value to set. Either assetId or assetKey is required. |
assetKey ​String​ | New value to set. Either assetId or assetKey is required. |
type ​ | Defines the Type that extends the Asset with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the Asset. |
fields ​ | Sets the Custom Fields fields for the Asset. |
{
"action": "setAssetCustomType",
"assetId": "{{assetId}}",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}
Set Asset CustomField
action ​String​ | "setAssetCustomField" |
assetId ​String​ | New value to set. Either assetId or assetKey is required. |
assetKey ​String​ | New value to set. Either assetId or assetKey is required. |
name ​String​ | Name of the Custom Field. |
value ​ | If value is absent or null , this field will be removed if it exists.
Removing a field that does not exist returns an InvalidOperation error.
If value is provided, it is set for the field defined by name . |
{
"action": "setAssetCustomField",
"assetId": "{{assetId}}",
"name": "exampleStringField",
"value": "TextString"
}
Delete Category
Deleting a root Category deletes the whole Category tree.
Delete Category by ID
manage_products:{projectKey}
manage_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the Category. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/categories/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
"version": 1,
"name": {
"en": "Hats"
},
"slug": {
"en": "hats"
},
"parent": {
"typeId": "category",
"id": "123456"
},
"ancestors": [],
"orderHint": "0.1",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
Delete Category by Key
manage_products:{projectKey}
manage_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the Category. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/categories/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
"version": 1,
"name": {
"en": "Hats"
},
"slug": {
"en": "hats"
},
"parent": {
"typeId": "category",
"id": "123456"
},
"ancestors": [],
"orderHint": "0.1",
"createdAt": "1970-01-01T00:00:00.001Z",
"lastModifiedAt": "1970-01-01T00:00:00.001Z"
}