Categories
Categories allow to organize products into hierarachical structures. They enabel 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
- DateTimelastModifiedAt
- DateTimename
- LocalizedStringslug
- 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 - Optionalancestors
- 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 - OptionalmetaTitle
- LocalizedString - OptionalmetaDescription
- LocalizedString - OptionalmetaKeywords
- LocalizedString - Optionalcustom
- CustomFields - Optionalassets
- Array of Asset
Can be used to store images, icons or movies related to this category.
CategoryDraft
key
String - Optional
User-specific unique identifier for the category.name
- LocalizedString - Requireddescription
- LocalizedString - Optionalparent
- 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 - OptionalmetaTitle
- LocalizedString - OptionalmetaDescription
- LocalizedString - OptionalmetaKeywords
- LocalizedString - Optionalcustom
- 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 - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- 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
Please find below the individual update actions provided on this endpoint.
Set Key
action
- String -"setKey"
key
- String - Optional
Ifkey
is absent ornull
, 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
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 - Requiredvalue
- * - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists.
Ifvalue
is provided, set thevalue
of the field defined by thename
.
The FieldDefinition determines the format for thevalue
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
- for EnumType and LocalizedEnumType fields: the
Add Asset
Adds an Asset.
action
- String -"addAsset"
asset
- AssetDraftposition
- Integer - Optional
When specified, the value might be0
and should be lower than the total of the assets list.
Remove Asset
Removes an Asset.
action
- String -"removeAsset"
assetId
- String orassetKey
- String - Required
Set Asset Key
Set or remove the key
of an an Asset.
action
- String -"setAssetKey"
assetId
- String - RequiredassetKey
- String - Optional
User-defined identifier for the asset.
If left blank or set tonull
, the asset key is unset/removed.
Change Asset Order
Changes the order of the assets
array. The new order is defined by listing the id
s of the assets.
action
- String -"changeAssetOrder"
assetOrder
- Array of String - Must contain all assetid
s.
Change Asset Name
action
- String -"changeAssetName"
assetId
- String orassetKey
- String - Requiredname
- LocalizedString
Set Asset Description
action
- String -"setAssetDescription"
assetId
- String orassetKey
- String - Requireddescription
- LocalizedString - Optional
Set Asset Tags
action
- String -"setAssetTags"
assetId
- String orassetKey
- String - Requiredtags
- Array of String - Optional
Set Asset Sources
action
- String -"setAssetSources"
assetId
- String orassetKey
- String - Requiredsources
- 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 orassetKey
- String - Requiredtype
- 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 orassetKey
- String - Requiredname
- String - Requiredvalue
- * - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists.
Ifvalue
is provided, set thevalue
of the field defined by thename
.
The FieldDefinition determines the format for thevalue
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
- for EnumType and LocalizedEnumType fields: the
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