Categories

B2CB2BB2XPRODUCT CATALOGAgenticLift

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.

Assigning Categories to Stores only controls Category visibility in Stores. It does not change discount or search behavior that is based on a Product's own categories.

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.

A maximum number of 10 000 Categories can be created per Project. This is a soft limit that can be increased per Project after a performance impact review. See Limit increase guidance.
Learn more about modeling Categories for shop navigation and other purposes in our self-paced Categorization module.
Learn more about how to build website navigation using Categories in our self-paced Category queries best practices module.

Category tree locking

To keep ancestor lists (paths) and Store assignments consistent, write operations on the Category tree lock the Category nodes they affect. If another operation already holds a required lock, the request fails with an InvalidOperation (400) error.

The lock scope depends on the operation:

  • Whole Category tree: a Change Parent action locks the entire Category tree in the Project for the duration of the request, because it can change the ancestor path of every Category below it. While it is in progress, any other Change Parent action, any Create Category request with a parent, and any Store update action anywhere in the Project fails.
  • Parent Category: a Create Category request with a parent locks that parent Category. The request fails if another Create Category request under the same parent, a Store update action on that parent or one of its existing children, or a Change Parent action is in progress. Creating a Category without a parent doesn't take this lock. Requests targeting different parents don't conflict with each other.
  • Category and its parent: the Set Stores, Add Store, and Remove Store actions lock the Category itself and its parent Category. Concurrent Store updates to the same Category, to sibling Categories, or to a Category and one of its direct children can conflict.
  • Category and its descendants: the Set Stores with Descendants, Add Store with Descendants, and Remove Store with Descendants actions don't change any Store when the API receives the request. The API only records the request and responds with 202 Accepted. A background process then updates the target Category and every descendant Category, which is eventually consistent. While the background process runs, it locks the target Category and its subtree, so Store updates, Change Parent actions, and Create Category requests with a parent for Categories in that subtree fail and should be retried. These actions are only available on the general endpoint and are rejected on the Store-specific endpoint.
To reduce conflicts, serialize requests that create or update Categories under the same parent. If a request fails because of a lock conflict, retry it after a short delay. For general retry recommendations, see Retry policies. For Category imports, see CategoryImport.

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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Category

as
application/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",
  "stores": [],
  "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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Category

as
application/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",
  "stores": [],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Get Category in Store BETA

Get Category in Store by ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/{id}
Retrieves a Category by its id if it is assigned to the specified Store or is global.
For global Categories, use the Get Category by ID endpoint.
If the Category does not exist in the Store, a ResourceNotFound error is returned.
OAuth 2.0 Scopes:
view_products:{projectKey}view_categories:{projectKey}view_products:{projectKey}:{storeKey}view_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the Category.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Category

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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",
  "stores": [
    {
      "typeId": "store",
      "key": "main-store"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Get Category in Store by Key

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/key={key}
Retrieves a Category by its key in the specified Store.
For global Categories, use the Get Category by Key endpoint.
If the Category does not exist in the Store, a ResourceNotFound error is returned.
OAuth 2.0 Scopes:
view_products:{projectKey}view_categories:{projectKey}view_products:{projectKey}:{storeKey}view_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the Category.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Category

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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",
  "stores": [
    {
      "typeId": "store",
      "key": "main-store"
    }
  ],
  "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
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
sort
​
String
​

Use to sort query results.

For more information, see Sorting.
The parameter can be passed multiple times.
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
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.
Response:
200

CategoryPagedQueryResponse

as
application/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",
      "stores": [],
      "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",
      "stores": [],
      "createdAt": "1970-01-01T00:00:00.001Z",
      "lastModifiedAt": "1970-01-01T00:00:00.001Z"
    }
  ]
}

Query Categories in Store BETA

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories
Retrieves Categories that are either assigned to the specified Store or global.
OAuth 2.0 Scopes:
view_products:{projectKey}view_categories:{projectKey}view_products:{projectKey}:{storeKey}view_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Query parameters:
where
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
sort
​
String
​

Use to sort query results.

For more information, see Sorting.
The parameter can be passed multiple times.
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
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.
Response:
200

CategoryPagedQueryResponse

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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",
      "stores": [],
      "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",
      "stores": [],
      "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 with the provided id. Returns a 200 status if the Category exists, or a 404 status 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 with the provided key. Returns a 200 status if the Category exists, or a 404 status 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 one or more Categories exist for the provided query predicate. Returns a 200 status if any Categories match the query predicate, or a 404 status 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
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
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}"

Check if Category exists in Store BETA

Check if Category exists in Store by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/{id}
Checks if a Category exists with the provided id in the specified Store. Returns a 200 status if the Category exists in the Store or is global, or a 404 status otherwise.
For global Categories, use the Check if Category exists by ID endpoint.
OAuth 2.0 Scopes:
view_products:{projectKey}view_categories:{projectKey}view_products:{projectKey}:{storeKey}view_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the Category.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Category exists in Store by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/key={key}
Checks if a Category exists with the provided key in the specified Store. Returns a 200 status if the Category exists in the Store or is global, or a 404 status otherwise.
For global Categories, use the Check if Category exists by Key endpoint.
OAuth 2.0 Scopes:
view_products:{projectKey}view_categories:{projectKey}view_products:{projectKey}:{storeKey}view_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the Category.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Category exists in Store by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories
Checks if one or more Categories exist in the Store for the provided query predicate. Returns a 200 status if any Categories match the query predicate, or a 404 status otherwise.
For global Categories, use the Check if Category exists by Query Predicate endpoint.
OAuth 2.0 Scopes:
view_products:{projectKey}view_categories:{projectKey}view_products:{projectKey}:{storeKey}view_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Query parameters:
where
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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 with a parent locks that parent Category. For details, see Category tree locking.
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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:CategoryDraftasapplication/json
Response:
201

Category

as
application/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",
  "stores": [],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Create Category in Store BETA

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories
Creates a Category in the specified Store.
For global Categories, use the Create Category endpoint.
Creating a Category with a parent locks that parent Category. For details, see Category tree locking.
Creating a Category produces the CategoryCreated Message.
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_categories:{projectKey}manage_products:{projectKey}:{storeKey}manage_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:CategoryDraftasapplication/json
Response:
201

Category

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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",
  "stores": [
    {
      "typeId": "store",
      "key": "main-store"
    }
  ],
  "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.
The response status code is 200 OK, unless the request contains a Set Stores with Descendants, Add Store with Descendants, or Remove Store with Descendants update action. In that case, the API responds with 202 Accepted, and the returned Category contains a warnings field with a StoreSettingOngoing Warning.
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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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.

Response:
200

Category

as
application/json
202

Category

as
application/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",
  "stores": [],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
202 Response Example: Categoryjson
{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 2,
  "name": {
    "en": "Hats"
  },
  "slug": {
    "en": "hats"
  },
  "parent": {
    "typeId": "category",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "ancestors": [
    {
      "typeId": "category",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "orderHint": "0.1",
  "stores": [
    {
      "typeId": "store",
      "key": "store-a"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.002Z",
  "warnings": [
    {
      "code": "StoreSettingOngoing",
      "message": "The store setting is still ongoing."
    }
  ]
}

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.
The response status code is 200 OK, unless the request contains a Set Stores with Descendants, Add Store with Descendants, or Remove Store with Descendants update action. In that case, the API responds with 202 Accepted, and the returned Category contains a warnings field with a StoreSettingOngoing Warning.
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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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.

Response:
200

Category

as
application/json
202

Category

as
application/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",
  "stores": [],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}
202 Response Example: Categoryjson
{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 2,
  "name": {
    "en": "Hats"
  },
  "slug": {
    "en": "hats"
  },
  "parent": {
    "typeId": "category",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "ancestors": [
    {
      "typeId": "category",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "orderHint": "0.1",
  "stores": [
    {
      "typeId": "store",
      "key": "store-a"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.002Z",
  "warnings": [
    {
      "code": "StoreSettingOngoing",
      "message": "The store setting is still ongoing."
    }
  ]
}

Update Category in Store BETA

Update Category in Store by ID

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/{id}
Updates a Category by its id in the specified Store.
To update a global Category, use the Update Category by ID endpoint.
If the Category does not exist in the Store, a ResourceNotFound error is returned.
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_categories:{projectKey}manage_products:{projectKey}:{storeKey}manage_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the Category.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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.

Response:
200

Category

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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",
  "stores": [
    {
      "typeId": "store",
      "key": "main-store"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Update Category in Store by Key

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/key={key}
Updates a Category by its key in the specified Store.
To update a global Category, use the Update Category by Key endpoint.
If the Category does not exist in the Store, a ResourceNotFound error is returned.
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_categories:{projectKey}manage_products:{projectKey}:{storeKey}manage_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the Category.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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.

Response:
200

Category

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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",
  "stores": [
    {
      "typeId": "store",
      "key": "main-store"
    }
  ],
  "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 omitted, any existing value is removed.

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

Change Name

action​
String​
"changeName"
name​
LocalizedString​

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​
LocalizedString​
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​
LocalizedString​

Value to set. If omitted, any existing value is removed.

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

Change Parent

This action locks the entire Category tree in the Project for the duration of the request. For details, see Category tree locking.
action​
String​
"changeParent"
parent​
CategoryResourceIdentifier​

New value to set as parent.

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

Set Stores BETA

This action locks the Category and its parent Category. For details, see Category tree locking.

Every direct child Category must be assigned to at least one Store in that set; otherwise, the action is rejected.

  • When updating a Category via the general endpoint, all Stores can be removed as a global Category is accessible in all Stores.
  • When updating a Category via the Store-specific endpoint, the stores field cannot be empty; otherwise, an InvalidOperation error is returned.
    If you do not have permission for every Store currently assigned to the Category, an Unauthorized error is returned.
action​
String​
"setStores"
stores​
Array of StoreResourceIdentifier​
Value to set. It replaces the entire set of Stores assigned to the Category.
If the stores field contains a Store that you do not have permission for, an InvalidInput error is returned.
Example: json
{
  "action": "setStores",
  "stores": [
    {
      "typeId": "store",
      "key": "store-a"
    },
    {
      "typeId": "store",
      "key": "store-b"
    }
  ]
}

Add Store BETA

This action locks the Category and its parent Category. For details, see Category tree locking.
action​
String​
"addStore"
store​
StoreResourceIdentifier​
Value to add to the Category's stores.
When called through an in-Store endpoint, the caller must have permission for the referenced Store.
Example: json
{
  "action": "addStore",
  "store": {
    "typeId": "store",
    "key": "store-a"
  }
}

Remove Store BETA

This action locks the Category and its parent Category. For details, see Category tree locking.

Every direct child Category must be assigned to at least one Store in that set; otherwise, the action is rejected.

  • When updating a Category via the general endpoint, all Stores can be removed as a global Category is accessible in all Stores.
  • When updating a Category via the Store-specific endpoint, you can remove the last Store only if at least one Store remains; otherwise, an InvalidOperation error is returned. If you do not have permission for the referenced Store, an InvalidInput error is returned.
action​
String​
"removeStore"
store​
StoreResourceIdentifier​
Value to remove from the Category's stores.
Example: json
{
  "action": "removeStore",
  "store": {
    "typeId": "store",
    "key": "store-a"
  }
}

Set Stores with Descendants BETA

Sets the stores of the Category and propagates the same set of Stores to all of its descendant Categories, replacing the entire set of Stores assigned to each affected Category in the subtree. Set an empty array to make the Category and its descendants global and accessible in all Stores.
This action is only available on the general endpoint.
If this action is used on the Store-specific endpoint, an InvalidOperation error is returned.
The API records the request and responds with 202 Accepted. The returned Category has the same stores as before and an incremented version, and the response contains a warnings field with a StoreSettingOngoing Warning. A background process then applies the change to the Category and to all of its descendant Categories, so the change is eventually consistent.
Because the background process locks the subtree while it runs, concurrent Store updates, Change Parent actions, and Create Category requests with a parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.
If the request contains another action that changes the stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.
If the Category has more than 1000 descendant Categories, an InvalidOperation error is returned.
The request is validated when the API receives it and again when the background process runs. If the change is no longer valid at that point, for example because the Stores of the parent Category changed or a referenced Store was deleted in the meantime, it isn't applied and no error is reported. All Categories in the subtree receive the same stores, so only the relation between the Category and its parent is validated.

Requests that change the Stores of the same subtree are processed in the order the background process receives them, which isn't necessarily the order they were sent in. Send the next request for the same subtree only after the previous change has been applied.

action​
String​
"setStoresWithDescendants"
stores​
Array of StoreResourceIdentifier​
Value to set on the Category and each of its descendant Categories. It replaces the entire set of Stores assigned to each Category in the subtree.
If a Store doesn't exist, a ReferencedResourceNotFound error is returned.
If the Category has a parent Category that is assigned to Stores and stores contains a Store the parent isn't assigned to, an InvalidInput error is returned.
If the Category has a parent Category that is assigned to Stores and stores is empty, an InvalidInput error is returned.
Example: json
{
  "action": "setStoresWithDescendants",
  "stores": [
    {
      "typeId": "store",
      "key": "store-a"
    },
    {
      "typeId": "store",
      "key": "store-b"
    }
  ]
}

Add Store with Descendants BETA

Adds a Store to the stores of the Category and to all of its descendant Categories.
This action is only available on the general endpoint.
If this action is used on the Store-specific endpoint, an InvalidOperation error is returned.
The API records the request and responds with 202 Accepted. The returned Category has the same stores as before and an incremented version, and the response contains a warnings field with a StoreSettingOngoing Warning. A background process then applies the change to the Category and to all of its descendant Categories, so the change is eventually consistent.
Because the background process locks the subtree while it runs, concurrent Store updates, Change Parent actions, and Create Category requests with a parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.
If the request contains another action that changes the stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.
If the Category has more than 1000 descendant Categories, an InvalidOperation error is returned.
The request is validated when the API receives it and again when the background process runs. If the change is no longer valid at that point, for example because the Stores of the parent Category changed or a referenced Store was deleted in the meantime, it isn't applied and no error is reported. Apart from the conditions described for store, the relations between Categories within the subtree aren't validated, as all of them receive the same change.

Requests that change the Stores of the same subtree are processed in the order the background process receives them, which isn't necessarily the order they were sent in. Send the next request for the same subtree only after the previous change has been applied.

action​
String​
"addStoreWithDescendants"
store​
StoreResourceIdentifier​
Value to add to the stores of the Category and each of its descendant Categories.
If the Store doesn't exist, a ReferencedResourceNotFound error is returned.
If the Category has a parent Category that is assigned to Stores and the Store isn't one of them, an InvalidInput error is returned.
If the Category isn't assigned to any Store and one of its descendant Categories is assigned to a different Store, an InvalidInput error is returned.
Example: json
{
  "action": "addStoreWithDescendants",
  "store": {
    "typeId": "store",
    "key": "store-a"
  }
}

Remove Store with Descendants BETA

Removes a Store from the stores of the Category and from all of its descendant Categories.

The Category itself doesn't need to be assigned to the Store, so that descendant Categories that still have it can be updated.

This action is only available on the general endpoint.
If this action is used on the Store-specific endpoint, an InvalidOperation error is returned.
The API records the request and responds with 202 Accepted. The returned Category has the same stores as before and an incremented version, and the response contains a warnings field with a StoreSettingOngoing Warning. A background process then applies the change to the Category and to all of its descendant Categories, so the change is eventually consistent.
Because the background process locks the subtree while it runs, concurrent Store updates, Change Parent actions, and Create Category requests with a parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.
If the request contains another action that changes the stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.
If the Category has more than 1000 descendant Categories, an InvalidOperation error is returned.
The request is validated when the API receives it and again when the background process runs. If the change is no longer valid at that point, for example because the Stores of the parent Category changed or a referenced Store was deleted in the meantime, it isn't applied and no error is reported. Apart from the conditions described for store, the relations between Categories within the subtree aren't validated, as all of them receive the same change.

Requests that change the Stores of the same subtree are processed in the order the background process receives them, which isn't necessarily the order they were sent in. Send the next request for the same subtree only after the previous change has been applied.

action​
String​
"removeStoreWithDescendants"
store​
StoreResourceIdentifier​
Value to remove from the stores of the Category and each of its descendant Categories.
If the Store doesn't exist, a ReferencedResourceNotFound error is returned.
If removing the Store leaves the Category without Stores while its parent Category is assigned to Stores, an InvalidInput error is returned.
If the Store is the only Store of a descendant Category that would then be left without any Store while its parent Category is still assigned to Stores, an InvalidInput error is returned.
Example: json
{
  "action": "removeStoreWithDescendants",
  "store": {
    "typeId": "store",
    "key": "store-a"
  }
}

Change OrderHint

action​
String​
"changeOrderHint"
orderHint​
String​
New value to set. Must be a decimal value between 0 and 1. When sorted in ascending order, Categories with a lower orderHint appear before those with a higher value (for example, 0.05 before 0.07).
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 omitted, any existing value is removed.

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

Set Meta Title

action​
String​
"setMetaTitle"
metaTitle​
LocalizedString​

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​
LocalizedString​

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​
LocalizedString​

Value to set.

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

Set Custom Type

action​
String​
"setCustomType"
type​
TypeResourceIdentifier​
Defines the Type that extends the Category with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Category.
fields​
FieldContainer​
Object containing the Custom Fields fields for the Category.
Required if at least one Custom Field is defined as required in the fieldDefinitions of the referenced Type.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

action​
String​
"setCustomField"
name​
String​
Name of the Custom Field.
value​
CustomFieldValue​
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": "exampleStringField",
  "value": "TextString"
}

Add Asset

action​
String​
"addAsset"
asset​
AssetDraft​

Value to append.

position​
Int32​
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 omitted, any existing value is 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​
LocalizedString​

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​
LocalizedString​

Value to set. If omitted, any existing value is 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​
TypeResourceIdentifier​
Defines the Type that extends the Asset with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Asset.
fields​
FieldContainer​
Object containing the Custom Fields fields for the Asset.
Required if at least one Custom Field is defined as required in the fieldDefinitions of the referenced Type.
Example: json
{
  "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​
CustomFieldValue​
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": "exampleStringField",
  "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
​
Int64
​

Last seen version of the resource.

expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Category

as
application/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",
  "stores": [],
  "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
​
Int64
​

Last seen version of the resource.

expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Category

as
application/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",
  "stores": [],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Delete Category in Store BETA

Deleting a root Category deletes the whole Category tree.

The Category and all its descendants are deleted only if you have permission for every Store referenced by any Category in the subtree.

Delete Category in Store by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/{id}
Deletes a Category by its id in the specified Store.
To delete a global Category, use the Delete Category by ID endpoint.
If you do not have permissions for a Store the Category is assigned to, an Unauthorized error is returned.
If the Category does not exist in the Store, a ResourceNotFound error is returned.
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_categories:{projectKey}manage_products:{projectKey}:{storeKey}manage_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the Category.
Query parameters:
version
​
Int64
​

Last seen version of the resource.

expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Category

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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",
  "stores": [
    {
      "typeId": "store",
      "key": "main-store"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Delete Category in Store by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/categories/key={key}
Deletes a Category by its key in the specified Store.
To delete a global Category, use the Delete Category by Key endpoint.
If you do not have permissions for a Store the Category is assigned to, an Unauthorized error is returned.
If the Category does not exist in the Store, a ResourceNotFound error is returned.
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_categories:{projectKey}manage_products:{projectKey}:{storeKey}manage_categories:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the Category.
Query parameters:
version
​
Int64
​

Last seen version of the resource.

expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Category

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/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",
  "stores": [
    {
      "typeId": "store",
      "key": "main-store"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Representations

Category

id​
String​

Unique identifier of the Category.

version​
Int64​

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​
LocalizedString​

Name of the Category.

slug​
LocalizedString​
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​
LocalizedString​

Description of the Category.

ancestors​
Array of CategoryReference​

Contains the parent path towards the root Category.

parent​
CategoryReference​

Parent Category of this Category.

orderHint​
String​
A decimal value between 0 and 1 used to order Categories within the same level of the category tree. When sorted in ascending order, Categories with a lower orderHint appear before those with a higher value (for example, 0.05 before 0.07).
metaTitle​
LocalizedString​

Name of the Category used by external search engines for improved search engine performance.

metaDescription​
LocalizedString​

Description of the Category used by external search engines for improved search engine performance.

metaKeywords​
LocalizedString​

Keywords related to the Category for improved search engine performance.

assets​
Array of Asset​

Media related to the Category.

stores​BETA
Array of StoreKeyReference​
Stores to which the Category is assigned and that you have permission to access.
If stores is empty, the Category is global and available in every Store.
If the Category is created via the Store-specific endpoint, the Store specified in the request path is automatically added to the field value.
custom​
CustomFields​

Custom Fields of the Category.

createdAt​
DateTime​

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

createdBy​BETA
CreatedBy​

IDs and references that created the Category.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the Category.

warnings​
Array of WarningObject​
Warnings about processing of a request. Appears in response to requests with response status code 202 Accepted.

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​
LocalizedString​

Name of the Category.

slug​
LocalizedString​
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​
LocalizedString​

Description of the Category.

parent​
CategoryResourceIdentifier​
Parent Category of the Category. The parent can be set by its id or key.
orderHint​
String​
A decimal value between 0 and 1 used to order Categories within the same level of the category tree. When sorted in ascending order, Categories with a lower orderHint appear before those with a higher value (for example, 0.05 before 0.07). If not set, a random value is assigned.
metaTitle​
LocalizedString​

Name of the Category used by external search engines for improved search engine performance.

metaDescription​
LocalizedString​

Description of the Category used by external search engines for improved search engine performance.

metaKeywords​
LocalizedString​

Keywords related to the Category for improved search engine performance.

assets​
Array of AssetDraft​

Media related to the Category.

stores​BETA
Array of StoreResourceIdentifier​
Stores to assign the Category to.

  • If not defined or set to an empty array, the Category is global.

  • If defined, you must have access to each referenced Store; otherwise, an InvalidInput error is returned.

    If the Category has a parent category, and the parent is assigned to Stores, this value must be a non-empty subset of the parent's Stores.

custom​
CustomFieldsDraft​

Custom Fields for the Category.

CategoryPagedQueryResponse

PagedQueryResult with results containing an array of Category.
limit​
Int64​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int64​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int64​

Actual number of results returned.

total​
Int64​
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

Reference to a Category.
id​
String​
Unique identifier of the referenced Category.
typeId​
ReferenceTypeId​
category
obj​
Category​
Contains the representation of the expanded Category. Only present in responses to requests with Reference Expansion for Categories.

CategoryKeyReference

Used by the Import API to identify a Category.
key​
String​

User-defined unique identifier of the referenced Category.

typeId​
ReferenceType​
category

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​
ReferenceTypeId​
category