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. Finally, a full text search with autosuggest over all Categories and their content is available via the GraphQL API.

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 Product Modeling 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_-]+$
name
LocalizedString

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.

externalId
String

Additional identifier for external systems like Customer Relationship Management (CRM) or Enterprise Resource Planning (ERP).

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_-]+$
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

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.

externalId
String

Additional identifier for external systems like Customer Relationship Management (CRM) or Enterprise Resource Planning (ERP).

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

Number of results requested.

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:

200Category

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/categories/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
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"
}

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:

200Category

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/categories/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
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"
}

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.

Response:

200CategoryPagedQueryResponse

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

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:CategoryDraft
Response:

201Category

Request Example:cURL
curl -X POST 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
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"
}

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:
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 409 Conflict will be returned.

actions

Update actions to be performed on the Category.

Response:

200Category

Request Example:cURL
curl -X POST 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
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"
}

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:
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 409 Conflict will be returned.

actions

Update actions to be performed on the Category.

Response:

200Category

Request Example:cURL
curl -X POST 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
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"
}

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"
}

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"
}
}

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"
}
}

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"
}
}

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.

Example: json
{
"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.

Example: json
{
"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.

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

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"
}
}

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"
}
}

Set Meta Keywords

action
String
"setMetaKeywords"
metaKeywords

Value to set.

Example: json
{
"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.

Example: json
{
"action" : "setCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"examplaryStringTypeField" : "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. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action" : "setCustomField",
"name" : "ExamplaryStringTypeField",
"value" : "TextString"
}

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"
}
}
}

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}}"
}

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}}"
}

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}}" ]
}

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"
}
}

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"
}
}

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}}"
}

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"
} ]
}

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.

Example: json
{
"action" : "setAssetCustomType",
"assetId" : "{{assetId}}",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"examplaryStringTypeField" : "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. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action" : "setAssetCustomField",
"assetId" : "{{assetId}}",
"name" : "ExamplaryStringTypeField",
"value" : "TextString"
}

Delete Category

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

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:

200Category

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/categories/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
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"
}

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:

200Category

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/categories/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
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"
}