Categories

Categories help organize your Products into various classifications. Customers can navigate a shop by browsing for related Products based on each Category.

Products can belong to multiple Categories, and there can be different Category hierarchies for various purposes and Channels. Categories are embedded in the Product search, enabling you to filter and search for Products by their respective parent and child Categories. You can create Categories and customize existing ones based on your specific content, workflows, and metadata requirements.

Categories include built-in fields for search engine optimization, such as unique and internationalizable URL slugs. Because slugs are an API resource for each Category, they can handle large quantities of Categories. The Merchant Center is also designed to handle these classifications of Categories.

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

Learn more about Categories 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.

Representations

Category

CategoryDraft

CategoryPagedQueryResponse

CategoryReference

CategoryKeyReference

CategoryResourceIdentifier

Category

`id` String	Unique identifier of the Category.
`version` Int	Current version of the Category.
`key` String	User-defined unique identifier of the Category. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`externalId` String	Additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP).
`name` 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	Decimal value between 0 and 1. Frontend applications can use this value for ordering Categories within the same level in the category tree.
`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.
`custom` CustomFields	Custom Fields for 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.

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	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` 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.
`custom` CustomFieldsDraft	Custom Fields for the Category.

CategoryPagedQueryResponse

PagedQueryResult with results containing an array of Category.

`limit` Int	Number of results requested. Default: `20`Minimum: `0`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10000`
`count` Int	Actual number of results returned.
`total` Int	Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter `withTotal=false`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of Category	Category matching the query.

CategoryReference

Reference to a Category.

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

CategoryKeyReference

Used by the Import API to identify a Category.

`key` String	User-defined unique identifier of the referenced Category.
`typeId` ReferenceType	`category` Type of referenced resource.

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` Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

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

Expansion

The parameter can be passed multiple times.

Response:

200

Category

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

Expansion

The parameter can be passed multiple times.

Response:

200

Category

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",
  "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` QueryPredicate	The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0` Maximum: `10000`
`withTotal` Boolean	Controls the calculation of the total number of query results. Set to `false` to improve query performance when the `total` is not needed. Default: `true`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200

CategoryPagedQueryResponse

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

QueryPredicate

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

Expansion

The parameter can be passed multiple times.

Request Body:CategoryDraftasapplication/json

Response:

201

Category

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

Expansion

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` Array of CategoryUpdateAction	Update actions to be performed on the Category.

Response:

200

Category

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

Expansion

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` Array of CategoryUpdateAction	Update actions to be performed on the Category.

Response:

200

Category

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",
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Set Key

`action` String	`"setKey"`
`key` String	Value to set. If empty, any existing value will be removed. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`

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 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` CategoryResourceIdentifier	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` 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	Sets the Custom Fields fields for the Category.

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` 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 `id`s.

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 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` 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	Sets the Custom Fields fields for the Asset.

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` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200

Category

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",
  "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` Expansion	The parameter can be passed multiple times.

Response:

200

Category

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",
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Categories

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Category.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CategoryDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CategoryPagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CategoryReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CategoryKeyReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CategoryResourceIdentifier.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get Category.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get Category by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get Category by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query Categories.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if Category exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if Category exists by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if Category exists by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if Category exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Create Category.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update Category.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update Category by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update Category by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update actions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change Name.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change Slug.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Description.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change Parent.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change OrderHint.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set External ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Meta Title.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Meta Description.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Meta Keywords.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Custom Type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set CustomField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Add Asset.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Remove Asset.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Asset Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change Asset Order.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change Asset Name.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Asset Description.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Asset Tags.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Asset Sources.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Asset Custom Type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Asset CustomField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete Category.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete Category by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete Category by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Representations

Category

CategoryDraft

CategoryPagedQueryResponse

CategoryReference

CategoryKeyReference

CategoryResourceIdentifier

Get Category

Get Category by ID

Get Category by Key

Query Categories

Check if Category exists

Check if Category exists by ID

Check if Category exists by Key

Check if Category exists by Query Predicate

Create Category

Update Category

Update Category by ID

Update Category by Key

Update actions

Set Key

Change Name

Change Slug

Set Description

Change Parent

Change OrderHint

Set External ID

Set Meta Title

Set Meta Description

Set Meta Keywords

Set Custom Type

Set CustomField

Add Asset

Remove Asset

Set Asset Key

Change Asset Order

Change Asset Name

Set Asset Description

Set Asset Tags

Set Asset Sources

Set Asset Custom Type

Set Asset CustomField

Delete Category

Delete Category by ID

Delete Category by Key