This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

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. 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

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. 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

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

ResourceIdentifier to a Category. Either 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
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:
200Categoryasapplication/json
Request Example:cURL
curl --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:
200Categoryasapplication/json
Request Example:cURL
curl --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:
200CategoryPagedQueryResponseasapplication/json
Request Example:cURL
curl --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"
}
]
}

Check if Category exists

Check if Category exists by ID

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

Checks if a Category exists for a given id. Returns a 200 OK status if the Category exists or a 404 Not Found otherwise.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/categories/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Category exists by Key

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

Checks if a Category exists for a given key. Returns a 200 OK status if the Category exists or a 404 Not Found otherwise.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/categories/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Category exists by Query Predicate

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

Checks if a Category exists for on a given Query Predicate. Returns a 200 OK status if any Categories match the Query Predicate or a 404 Not Found otherwise.

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

Query Predicates on Categories are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/categories -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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

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

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

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"

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

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

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.

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

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

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:
200Categoryasapplication/json
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:
200Categoryasapplication/json
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"
}