Categories

Categories are used to organize products in a hierarchical structure.

Representations

Category

CategoryDraft

Get Category

Get Category by ID

Endpoint: /{projectKey}/categories/{id}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: Category

Get Category by Key

Endpoint: /{projectKey}/categories/key={key}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: Category

Query Categories

Endpoint: /{projectKey}/categories
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results array of Category
Query Parameters:

Create a Category

Endpoint: /{projectKey}/categories
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Request Representation: CategoryDraft
Response Representation: Category

Creating a category produces the CategoryCreated message.

Update Category

Update Category by ID

Endpoint: /{projectKey}/categories/{id}
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: Category
Fields:

Update Category by Key

Endpoint: /{projectKey}/categories/key={key}
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: Category
Fields:

Update Actions
Please find below the individual update actions provided on this endpoint.


Set Key

Change Name

Change Slug

Changing the slug produces the CategorySlugChanged message.

Set Description

Change Parent

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

Change OrderHint

Set External ID

Sets a new ID which can be used as additional identifier for external Systems like CRM or ERP.

Set Meta Title

Set Meta Description

Set Meta Keywords

Set Custom Type

This action sets or removes the custom type for an existing category.

This action overwrites any existing custom type and fields.

Set CustomField

Add Asset

Adds an Asset.

Remove Asset

Removes an Asset.

Change Asset Order

Changes the order of the assets array. The new order is defined by listing the ids of the assets.

Change Asset Name

Set Asset Description

Set Asset Tags

Set Asset Sources

Set Asset Custom Type

This action sets, overwrites or removes the custom type and fields for an existing Asset.

Set Asset Custom Field

This action sets, overwrites or removes any existing custom field for an existing Asset.

Delete Category

When a category is deleted, all the descending categories will also be deleted. Deleting the root category deletes the whole category tree.

The deleted category will be removed from all those products that had that category assigned in their ProductData.

Delete Category by ID

Endpoint: /{projectKey}/categories/{id}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:

Delete Category by Key

Endpoint: /{projectKey}/categories/key={key}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters: