Categories

Representations

Category

• id - String
  The unique ID of the category.
• key - String - Optional
  User-specific unique identifier for the category.
• version - Number
  The current version of the category.
• createdAt - DateTime
• createdBy - CreatedBy BETA
  Present on resources created after 2019-02-01 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy BETA
  Present on resources updated after 2019-02-01 except for events not tracked.
• name - LocalizedString
• slug - LocalizedString - must match the pattern [-a-zA-Z0-9_]{2,256}
  human-readable identifiers usually used as deep-link URL to the related category. Each slug is unique across a project, but a category can have the same slug for different languages.
  For good performance, indexes are provided for the first 15 languages set on the Project.
• description - LocalizedString - Optional
• ancestors - Array of Reference to a Category
  Contains the parent path towards the root category.
• parent - Reference to a Category - Optional
  A category that is the parent of this category in the category tree.
• orderHint - String
  An attribute as base for a custom category order in one level.
• externalId - String - Optional
• metaTitle - LocalizedString - Optional
• metaDescription - LocalizedString - Optional
• metaKeywords - LocalizedString - Optional
• custom - CustomFields - Optional
• assets - Array of Asset
  Can be used to store images, icons or movies related to this category.

CategoryDraft

• key - String - Optional
  User-defined unique identifier for the Category. Keys can only contain alphanumeric characters (a-Z, 0-9), underscores and hyphens (_, -) and be between 2 and 256 characters.
• name - LocalizedString - Required
• description - LocalizedString - Optional
• parent - ResourceIdentifier of a Category - Optional
  A category that is the parent of this category in the category tree.
  The parent can be set by its ID or by its key.
• slug - LocalizedString - Required
  human-readable identifier usually used as deep-link URL to the related category. Allowed are alphabetic, numeric, underscore (_) and hyphen (-) characters. Maximum size is 256. Must be unique across a project! The same category can have the same slug for different languages.
• orderHint - String - Optional
  An attribute as base for a custom category order in one level. A random value will be assigned by API if not set.
• externalId - String - Optional
• metaTitle - LocalizedString - Optional
• metaDescription - LocalizedString - Optional
• metaKeywords - LocalizedString - Optional
• custom - CustomFieldsDraft - Optional
  The custom fields.
• assets - Array of AssetDraft - Optional

Get Category

Get Category by ID

Endpoint: /{projectKey}/categories/{id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey} or view_categories:{projectKey}
Response Representation: Category

Get Category by Key

Endpoint: /{projectKey}/categories/key={key}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey} or view_categories:{projectKey}
Response Representation: Category

Query Categories

Endpoint: /{projectKey}/categories
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey} or view_categories:{projectKey}
Response Representation: PagedQueryResult with results containing an array of Category
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Create a Category

Endpoint: /{projectKey}/categories
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey} or manage_categories:{projectKey}
Request Representation: CategoryDraft
Response Representation: Category

Creating a category produces the CategoryCreatedMessage.

Update Category

Update Category by ID

Endpoint: /{projectKey}/categories/{id}
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey} or manage_categories:{projectKey}
Response Representation: Category
Fields:

• version - Number - Required
  The expected version of the category on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the category.

Update Category by Key

Endpoint: /{projectKey}/categories/key={key}
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey} or manage_categories:{projectKey}
Response Representation: Category
Fields:

• version - Number - Required
  The expected version of the category on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the category.

Update actions

Set Key

• action - String - "setKey"
• key - String - Optional
  If key is absent or null, the existing key, if any, will be removed.

Change Name

• action - String - "changeName"
• name - LocalizedString - Required

Change Slug

• action - String - "changeSlug"
• slug - LocalizedString - Required
  Allowed are alphabetic, numeric, underscore (_) and hyphen (-) characters. Maximum size is 256.

Changing the slug produces the CategorySlugChangedMessage.

Set Description

• action - String - "setDescription"
• description - LocalizedString - Optional

Change Parent

• action - String - "changeParent"
• parent - ResourceIdentifier of a Category - Required

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

Change OrderHint

• action - String - "changeOrderHint"
• orderHint - String - Required

Set External ID

Sets a new ID which can be used as additional identifier for external Systems like Customer Relationship Management (CRM) or Enterprise Resource Planning (ERP).

• action - String - "setExternalId"
• externalId - String - Optional
  If not defined, the external ID is unset.

Set Meta Title

• action - String - "setMetaTitle"
• metaTitle - LocalizedString - Optional

Set Meta Description

• action - String - "setMetaDescription"
• metaDescription - LocalizedString - Optional

Set Meta Keywords

• action - String - "setMetaKeywords"
• metaKeywords - LocalizedString - Optional

Set Custom Type

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

• action - String - "setCustomType"

• type - ResourceIdentifier of a Type - Optional
  If absent, the custom type and any existing CustomFields are removed.

• fields - * - Optional
  A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.

  This action overwrites any existing custom type and fields.

Set CustomField

Add Asset

Adds an Asset.

• action - String - "addAsset"
• asset - AssetDraft
• position - Integer - Optional
  When specified, the value might be 0 and should be lower than the total of the assets list.

Remove Asset

Removes an Asset.

• action - String - "removeAsset"
• assetId - String or assetKey - String - Required

Set Asset Key

Set or remove the key of an Asset.

• action - String - "setAssetKey"
• assetId - String - Required
• assetKey - String - Optional
  User-defined identifier for the asset.
  If left blank or set to null, the asset key is unset/removed.

Change Asset Order

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 - Must contain all asset ids.

Change Asset Name

• action - String - "changeAssetName"
• assetId - String or assetKey - String - Required
• name - LocalizedString

Set Asset Description

• action - String - "setAssetDescription"
• assetId - String or assetKey - String - Required
• description - LocalizedString - Optional

Set Asset Tags

• action - String - "setAssetTags"
• assetId - String or assetKey - String - Required
• tags - Array of String - Optional

Set Asset Sources

• action - String - "setAssetSources"
• assetId - String or assetKey - String - Required
• sources - Array of AssetSource - Requires at least one entry

Set Asset Custom Type

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

• action - String - "setAssetCustomType"
• assetId - String or assetKey - String - Required
• type - ResourceIdentifier of a Type - Optional
  If set, the custom type is set to this new value.
  If absent, the custom type and any existing custom fields are removed.
• fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
  If set, the custom fields are set to this new value.

Set Asset Custom Field

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

• action - String - "setAssetCustomField"
• assetId - String or assetKey - String - Required
• name - String - Required
• value - Value - Optional
  If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

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
OAuth 2.0 Scopes: manage_products:{projectKey} or manage_categories:{projectKey}
Query Parameters:

• version - Number - Required

Delete Category by Key

Endpoint: /{projectKey}/categories/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey} or manage_categories:{projectKey}
Query Parameters:

• version - Number - Required