Categories

Categories allow to organize products into hierarachical structures. They enable creating multiple classifications of products for shop navigation and other purposes.

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.

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
  • lastModifiedAt - DateTime
  • 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:

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

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

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

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.

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

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