Categories

Products can be in any number of categories and there can be multiple category hieararchies for different purposes or channels. Categories are embedded in the product search so that you can filter products by their assignment to categories, including products in child categories. Categories are also an own, customizable resource that you can extend with own content, workflow and metadata. Relevant SEO fields are built-in, e.g. uniqueness-checked and internationalizable URL components (“slugs”). Since they are an API resource per category they scale well into very large numbers of categories and the Merchant Center is also well prepared for managing such large classifications. Finally, a full text search with autosuggest over all categories and their own content is available via the GraphQL API.

Deciding how to model your categories for navigation and other purposes is an important part of working with the platform. For more information, see the Product Modeling Guide.

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 1/02/2019 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy beta
  Present on resources updated after 1/02/2019 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.
• 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 to 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
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:

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

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:

• 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
OAuth2 Scopes: manage_products:{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
  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.

  If key is absent or null, this field will be removed if it exists.

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

Set Description

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

Change Parent

• action - String - "changeParent"
• parent - ResourceIdentifier to 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 CRM or 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 to 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

• action - String - "setCustomField"
• name - String - Required
• value - * - Optional
  If value is absent or null, this field will be removed if it exists.
  If value is provided, set the  value of the field defined by the name.
  The FieldDefinition determines the format for the value to be provided.
  In particular, for the fields definitions, value has to be provided as:
  • for EnumType and LocalizedEnumType fields: the key of the EnumValue or the LocalizedEnumValue
  • for LocalizedStringType fields: the LocalizedString object
  • for MoneyType fields: the Money object
  • for SetType fields: the entire Set object
  • for ReferenceType fields: the Reference object

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 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 to 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 - * - Optional
  If value is absent or null, this field will be removed if it exists.
  If value is provided, set the  value of the field defined by the name.
  The FieldDefinition determines the format for the value to be provided.
  In particular, for the fields definitions, value has to be provided as:
  • for EnumType and LocalizedEnumType fields: the key of the EnumValue or the LocalizedEnumValue
  • for LocalizedStringType fields: the LocalizedString object
  • for MoneyType fields: the Money object
  • for SetType fields: the entire Set object
  • for ReferenceType fields: the Reference object

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:

• version - Number - Required

Delete Category by Key

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

• version - Number - Required

• Representations
  • Category
  • CategoryDraft
• Get Category
  • Get Category by ID
  • Get Category by Key
• Query Categories
• Create a 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 Custom Field
• Delete Category
  • Delete Category by ID
  • Delete Category by Key