Categories

Categories organize Products into hierarchical structures. They enable creating multiple classifications of Products for shop navigation and other purposes.

Products can be in any number of Categories and there can be multiple Category hierarchies for different purposes or Channels. Categories are embedded in the Product search so that you can filter Products by their assignment to Categories, including Products in child Categories. Categories are also an own, customizable resource that can be extended with your own content, workflow, and metadata. Relevant search engine optimization fields are built-in, for example, uniqueness-checked and internationalizable URL components ("slugs"). Since they are an API resource per Category, they scale well into very large numbers of Categories and the Merchant Center is also well prepared for managing such large classifications.

Deciding how to model your categories for navigation and other purposes is an important part of working with the API. For more information, see the Categories Guide.

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: 2MaxLength: 256Pattern: ^[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 used to order Categories that are on 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

Custom Fields for the Category.

createdAt

Date and time (UTC) the Category was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the Category was last updated.

lastModifiedByBETA

Present on resources updated after 1 February 2019 except for events not tracked.

CategoryDraft

key
String

User-defined unique identifier for the Category.

MinLength: 2MaxLength: 256Pattern: ^[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. A Category can have the same slug for different Locales, but it must be unique across the Project. Valid slugs must match the pattern ^[A-Za-z0-9_-]{2,256}+$.

description

Description of the Category.

Parent Category of the Category. The parent can be set by its id or key.

orderHint
String

Decimal value between 0 and 1 used to order Categories that are on 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

PagedQueryResult with results containing an array of Category.

limit
Int
offset
Int

Number of elements skipped.

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
String
"category"

References a Category.

obj

Contains the representation of the expanded Category. Only present in responses to requests with Reference Expansion for Categories.

CategoryResourceIdentifier

id
String

Unique identifier of the referenced Category. Either id or key is required.

key
String

User-defined unique identifier of the referenced Category. Either id or key is required.

typeId
String
"category"

References a Category.

Get Category

Get Category by ID

GET
https://api.{region}.commercetools.com/{projectKey}/categories/{id}

Either the scope view_products:{projectKey} or view_categories:{projectKey} is required.

OAuth 2.0 Scopes:
view_products:{projectKey}, view_categories:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Category.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/categories/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Categoryjson
{
"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"
}
Clipboard icon

Get Category by Key

GET
https://api.{region}.commercetools.com/{projectKey}/categories/key={key}

Either the scope view_products:{projectKey} or view_categories:{projectKey} is required.

OAuth 2.0 Scopes:
view_products:{projectKey}, view_categories:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Category.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/categories/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Categoryjson
{
"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"
}
Clipboard icon

Query Categories

GET
https://api.{region}.commercetools.com/{projectKey}/categories

Either the scope view_products:{projectKey} or view_categories:{projectKey} is required.

OAuth 2.0 Scopes:
view_products:{projectKey}, view_categories:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

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
offset
Int

Number of elements skipped.

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.

Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/categories -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: CategoryPagedQueryResponsejson
{
"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"
} ]
}
Clipboard icon

Create Category

POST
https://api.{region}.commercetools.com/{projectKey}/categories

Either the scope manage_products:{projectKey} or manage_categories:{projectKey} is required.

Creating a Category produces the CategoryCreated Message.

OAuth 2.0 Scopes:
manage_products:{projectKey}, manage_categories:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:CategoryDraftasapplication/json
Response:
201Categoryasapplication/json
Request Example:cURL
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
Clipboard icon
201 Response Example: Categoryjson
{
"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"
}
Clipboard icon

Update Category

Update Category by ID

POST
https://api.{region}.commercetools.com/{projectKey}/categories/{id}

Either the scope manage_products:{projectKey} or manage_categories:{projectKey} is required.

OAuth 2.0 Scopes:
manage_products:{projectKey}, manage_categories:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Category.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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 is returned.

actions

Update actions to be performed on the Category.

Response:
200Categoryasapplication/json
Request Example:cURL
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
Clipboard icon
200 Response Example: Categoryjson
{
"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"
}
Clipboard icon

Update Category by Key

POST
https://api.{region}.commercetools.com/{projectKey}/categories/key={key}

Either the scope manage_products:{projectKey} or manage_categories:{projectKey} is required.

OAuth 2.0 Scopes:
manage_products:{projectKey}, manage_categories:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Category.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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 is returned.

actions

Update actions to be performed on the Category.

Response:
200Categoryasapplication/json
Request Example:cURL
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
Clipboard icon
200 Response Example: Categoryjson
{
"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"
}
Clipboard icon

Update actions

Set Key

action
String
"setKey"
key
String

Value to set. If empty, any existing value will be removed.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
Example: json
{
"action" : "setKey",
"key" : "myNewKey"
}
Clipboard icon

Change Name

action
String
"changeName"
name

New value to set. Must not be empty.

Example: json
{
"action" : "changeName",
"name" : {
"de" : "neuer Category Name",
"en" : "new category name"
}
}
Clipboard icon

Change Slug

Changing the slug produces the CategorySlugChanged Message.

action
String
"changeSlug"
slug

New value to set. Must not be empty. A Category can have the same slug for different Locales, but it must be unique across the Project. Valid slugs must match the pattern ^[A-Za-z0-9_-]{2,256}+$.

Example: json
{
"action" : "changeSlug",
"slug" : {
"de" : "meine-kategorie",
"en" : "my-category"
}
}
Clipboard icon

Set Description

action
String
"setDescription"
description

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setDescription",
"description" : {
"de" : "This is a category description",
"en" : "Dies ist eine Kategorie-Beschreibung"
}
}
Clipboard icon

Change Parent

Warning icon

Changing parents should not be done concurrently. Concurrent changes of parent categories might lead to corrupted ancestor lists (paths).

action
String
"changeParent"

New value to set as parent.

Example: json
{
"action" : "changeParent",
"parent" : {
"typeId" : "category",
"id" : "{{category-id}}"
}
}
Clipboard icon

Change OrderHint

action
String
"changeOrderHint"
orderHint
String

New value to set. Must be a decimal value between 0 and 1.

Example: json
{
"action" : "changeOrderHint",
"orderHint" : "0.1"
}
Clipboard icon

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.

Example: json
{
"action" : "setExternalId",
"externalId" : "externalIdString"
}
Clipboard icon

Set Meta Title

action
String
"setMetaTitle"
metaTitle

Value to set.

Example: json
{
"action" : "setMetaTitle",
"metaTitle" : {
"de" : "Dies ist mein Meta-Title",
"en" : "This is my meta title"
}
}
Clipboard icon

Set Meta Description

action
String
"setMetaDescription"
metaDescription

Value to set.

Example: json
{
"action" : "setMetaDescription",
"metaDescription" : {
"de" : "Dies ist meine MetaDecription",
"en" : "this is my meta description"
}
}
Clipboard icon

Set Meta Keywords

action
String
"setMetaKeywords"
metaKeywords

Value to set.

Example: json
{
"action" : "setMetaKeywords",
"metaKeywords" : {
"de" : "commercetools, genial",
"en" : "commercetools, aweseome"
}
}
Clipboard icon

Set Custom Type

action
String
"setCustomType"

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.

Example: json
{
"action" : "setCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"exampleStringTypeField" : "TextString"
}
}
Clipboard icon

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.

Example: json
{
"action" : "setCustomField",
"name" : "ExampleStringTypeField",
"value" : "TextString"
}
Clipboard icon

Add Asset

action
String
"addAsset"
asset

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.

Example: json
{
"action" : "addAsset",
"asset" : {
"sources" : [ {
"uri" : "https://www.commercetools.de/ct-logo.svg",
"key" : "vector"
} ],
"name" : {
"de" : "commercetools Logo",
"en" : "commercetools logo"
}
}
}
Clipboard icon

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.

Example: json
{
"action" : "removeAsset",
"assetId" : "{{assetId}}"
}
Clipboard icon

Set Asset Key

Set or remove the 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.

Example: json
{
"action" : "setAssetKey",
"assetId" : "{{assetId}}"
}
Clipboard icon

Change Asset Order

This update action changes the order of the assets array. The new order is defined by listing the ids of the Assets.

action
String
"changeAssetOrder"
assetOrder
Array of String

New value to set. Must contain all Asset ids.

Example: json
{
"action" : "changeAssetOrder",
"assetOrder" : [ "{{assetId1}}", "{{assetId2}}" ]
}
Clipboard icon

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.

Example: json
{
"action" : "changeAssetName",
"assetId" : "{{assetId}}",
"name" : {
"de" : "Mein Asset",
"en" : "My asset"
}
}
Clipboard icon

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.

Example: json
{
"action" : "setAssetDescription",
"assetId" : "{{assetId}}",
"description" : {
"de" : "Dies ist eine Asset-Beschreibung",
"en" : "This is an asset description"
}
}
Clipboard icon

Set Asset Tags

action
String
"setAssetTags"
assetId
String

New value to set. Either assetId or assetKey is required.

assetKey
String

New value to set. Either assetId or assetKey is required.

tags
Array of String

Keywords for categorizing and organizing Assets.

Example: json
{
"action" : "setAssetTags",
"assetId" : "{{assetId}}"
}
Clipboard icon

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.

Example: json
{
"action" : "setAssetSources",
"assetId" : "{{assetId}}",
"sources" : [ {
"uri" : "https://www.commercetools.de/ct-logo.svg",
"key" : "vector"
} ]
}
Clipboard icon

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.

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.

Example: json
{
"action" : "setAssetCustomType",
"assetId" : "{{assetId}}",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"exampleStringTypeField" : "TextString"
}
}
Clipboard icon

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.

Example: json
{
"action" : "setAssetCustomField",
"assetId" : "{{assetId}}",
"name" : "ExampleStringTypeField",
"value" : "TextString"
}
Clipboard icon

Delete Category

Information icon

The deleted Category will be removed from all the Products that had the Category assigned in their ProductData.

Warning icon

Deleting a root Category deletes the whole Category tree.

Delete Category by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/categories/{id}

Either the scope manage_products:{projectKey} or manage_categories:{projectKey} is required.

OAuth 2.0 Scopes:
manage_products:{projectKey}, manage_categories:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Category.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/categories/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Categoryjson
{
"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"
}
Clipboard icon

Delete Category by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/categories/key={key}

Either the scope manage_products:{projectKey} or manage_categories:{projectKey} is required.

OAuth 2.0 Scopes:
manage_products:{projectKey}, manage_categories:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Category.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/categories/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Categoryjson
{
"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"
}
Clipboard icon