Queries and mutations for managing Categories in the platform.

Queries

Query Categories

QUERYcategories
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​

Get Category

QUERYcategory
Arguments
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Category

Mutations

Create Category

MUTATIONcreateCategory
Arguments
draft​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

Output:Category

Update Category

MUTATIONupdateCategory
Arguments
version​
Long​
actions​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Category

Delete Category

MUTATIONdeleteCategory
Arguments
version​
Long​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Category

Output types

Category

id​
String​

Unique identifier of the Category.

key​
String​

User-defined unique identifier of the Category.

version​
Long​

Current version of the Category.

name​
String​

Name of the Category.

nameAllLocales​
Array of LocalizedString​

Name of the Category.

description​
String​

Description of the Category.

descriptionAllLocales​
Array of LocalizedString​

Description of the Category.

slug​
String​
User-defined identifier used as a deep-link URL to the related Category per Locale. A Category can have the same slug for different Locales, but they are unique across the Project. Valid slugs match the pattern ^[A-Za-z0-9_-]{2,256}+$. For good performance, indexes are provided for the first 15 languages set in a Project.
slugAllLocales​
Array of LocalizedString​
User-defined identifier used as a deep-link URL to the related Category per Locale. A Category can have the same slug for different Locales, but they are unique across the Project. Valid slugs match the pattern ^[A-Za-z0-9_-]{2,256}+$. For good performance, indexes are provided for the first 15 languages set in a Project.
ancestorsRef​
Array of Reference​

Contains the parent path towards the root Category.

ancestors​
Array of Category​

Contains the parent path towards the root Category.

parentRef​

Parent Category of this Category.

parent​

Parent Category of this Category.

orderHint​
String​
A decimal value between 0 and 1 used to order Categories within the same level of the category tree. When sorted in ascending order, Categories with a lower orderHint appear before those with a higher value (for example, 0.05 before 0.07).
externalId​
String​

Additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP).

metaTitle​
String​

Name of the Category used by external search engines for improved search engine performance.

metaTitleAllLocales​
Array of LocalizedString​

Name of the Category used by external search engines for improved search engine performance.

metaKeywords​
String​

Keywords related to the Category for improved search engine performance.

metaKeywordsAllLocales​
Array of LocalizedString​

Keywords related to the Category for improved search engine performance.

metaDescription​
String​

Description of the Category used by external search engines for improved search engine performance.

metaDescriptionAllLocales​
Array of LocalizedString​

Description of the Category used by external search engines for improved search engine performance.

stagedProductCount​
Int​

Number of staged products in the category subtree.

childCount​
Int​

Number of direct child categories.

children​
Array of Category​
Direct child categories. The maximum number of child categories that can be fetched is 150. If the actual number of child categories exceeds this limit, the query will fail.
createdAt​

Date and time (UTC) the Category was initially created.

lastModifiedAt​

Date and time (UTC) the Category was last updated.

assets​
Array of Asset​

Media related to the Category.

storesRef​
Array of KeyReference​
Stores to which the Category is assigned and that you have permission to access.
If stores is empty, the Category is global and available in every Store.
If the Category is created via the Store-specific endpoint, the Store specified in the request path is automatically added to the field value.
stores​
Array of Store​
Stores to which the Category is assigned and that you have permission to access.
If stores is empty, the Category is global and available in every Store.
If the Category is created via the Store-specific endpoint, the Store specified in the request path is automatically added to the field value.
custom​

Custom Fields of the Category.

createdBy​

IDs and references that created the Category.

lastModifiedBy​

IDs and references that last modified the Category.

CategoryQueryResult

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of Category​

Input types

CategoryDraft

key​
String​

User-defined unique identifier for the Category.

This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing Categories with the Import API and the Merchant Center.
name​

Name of the Category.

description​

Description of the Category.

custom​

Custom Fields for the Category.

slug​
User-defined identifier used as a deep-link URL to the related Category. A Category can have the same slug for different Locales, but it must be unique across the Project. Valid slugs must match the pattern ^[A-Za-z0-9_-]{2,256}+$.
externalId​
String​

Additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP).

metaTitle​

Name of the Category used by external search engines for improved search engine performance.

metaDescription​

Description of the Category used by external search engines for improved search engine performance.

metaKeywords​

Keywords related to the Category for improved search engine performance.

orderHint​
String​
A decimal value between 0 and 1 used to order Categories within the same level of the category tree. When sorted in ascending order, Categories with a lower orderHint appear before those with a higher value (for example, 0.05 before 0.07). If not set, a random value is assigned.
Parent Category of the Category. The parent can be set by its id or key.
stores​
Stores to assign the Category to.
  • If not defined or set to an empty array, the Category is global.

  • If defined, you must have access to each referenced Store; otherwise, an InvalidInput error is returned.

    If the Category has a parent category, and the parent is assigned to Stores, this value must be a non-empty subset of the parent's Stores.

assets​
Array of AssetDraftInput​

Media related to the Category.

Default: []​

AssetDraftInput

key​
String​
name​
description​
custom​
sources​
Array of AssetSourceInput​
tags​
Array of String​

AssetSourceInput

uri​
String​
key​
String​
dimensions​
contentType​
String​

AssetDimensionsInput

width​
Int​
height​
Int​

CategoryUpdateAction

addAsset​
addStore​
addStoreWithDescendants​
changeAssetName​
changeAssetOrder​
changeName​
changeOrderHint​
changeSlug​
changeParent​
removeAsset​
removeStore​
removeStoreWithDescendants​
setAssetCustomField​
setAssetCustomType​
setAssetDescription​
setAssetKey​
setAssetSources​
setAssetTags​
setCustomField​
setCustomType​
setDescription​
setKey​
setMetaDescription​
setMetaKeywords​
setMetaTitle​
setStores​
setStoresWithDescendants​
setExternalId​

AddCategoryStoreWithDescendants

Adds a Store to the stores of the Category and to all of its descendant Categories.
This action is only available on the general endpoint.
If this action is used on the Store-specific endpoint, an InvalidOperation error is returned.
The API records the request and responds with 202 Accepted. The returned Category has the same stores as before and an incremented version, and the response contains a warnings field with a StoreSettingOngoing Warning. A background process then applies the change to the Category and to all of its descendant Categories, so the change is eventually consistent.
Because the background process locks the subtree while it runs, concurrent Store updates, Change Parent actions, and Create Category requests with a parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.
If the request contains another action that changes the stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.
If the Category has more than 1000 descendant Categories, an InvalidOperation error is returned.
The request is validated when the API receives it and again when the background process runs. If the change is no longer valid at that point, for example because the Stores of the parent Category changed or a referenced Store was deleted in the meantime, it isn't applied and no error is reported. Apart from the conditions described for store, the relations between Categories within the subtree aren't validated, as all of them receive the same change.

Requests that change the Stores of the same subtree are processed in the order the background process receives them, which isn't necessarily the order they were sent in. Send the next request for the same subtree only after the previous change has been applied.

Value to add to the stores of the Category and each of its descendant Categories.
If the Store doesn't exist, a ReferencedResourceNotFound error is returned.
If the Category has a parent Category that is assigned to Stores and the Store isn't one of them, an InvalidInput error is returned.
If the Category isn't assigned to any Store and one of its descendant Categories is assigned to a different Store, an InvalidInput error is returned.

RemoveCategoryStoreWithDescendants

Removes a Store from the stores of the Category and from all of its descendant Categories.

The Category itself doesn't need to be assigned to the Store, so that descendant Categories that still have it can be updated.

This action is only available on the general endpoint.
If this action is used on the Store-specific endpoint, an InvalidOperation error is returned.
The API records the request and responds with 202 Accepted. The returned Category has the same stores as before and an incremented version, and the response contains a warnings field with a StoreSettingOngoing Warning. A background process then applies the change to the Category and to all of its descendant Categories, so the change is eventually consistent.
Because the background process locks the subtree while it runs, concurrent Store updates, Change Parent actions, and Create Category requests with a parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.
If the request contains another action that changes the stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.
If the Category has more than 1000 descendant Categories, an InvalidOperation error is returned.
The request is validated when the API receives it and again when the background process runs. If the change is no longer valid at that point, for example because the Stores of the parent Category changed or a referenced Store was deleted in the meantime, it isn't applied and no error is reported. Apart from the conditions described for store, the relations between Categories within the subtree aren't validated, as all of them receive the same change.

Requests that change the Stores of the same subtree are processed in the order the background process receives them, which isn't necessarily the order they were sent in. Send the next request for the same subtree only after the previous change has been applied.

Value to remove from the stores of the Category and each of its descendant Categories.
If the Store doesn't exist, a ReferencedResourceNotFound error is returned.
If removing the Store leaves the Category without Stores while its parent Category is assigned to Stores, an InvalidInput error is returned.
If the Store is the only Store of a descendant Category that would then be left without any Store while its parent Category is still assigned to Stores, an InvalidInput error is returned.

SetCategoryStoresWithDescendants

Sets the stores of the Category and propagates the same set of Stores to all of its descendant Categories, replacing the entire set of Stores assigned to each affected Category in the subtree. Set an empty array to make the Category and its descendants global and accessible in all Stores.
This action is only available on the general endpoint.
If this action is used on the Store-specific endpoint, an InvalidOperation error is returned.
The API records the request and responds with 202 Accepted. The returned Category has the same stores as before and an incremented version, and the response contains a warnings field with a StoreSettingOngoing Warning. A background process then applies the change to the Category and to all of its descendant Categories, so the change is eventually consistent.
Because the background process locks the subtree while it runs, concurrent Store updates, Change Parent actions, and Create Category requests with a parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.
If the request contains another action that changes the stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.
If the Category has more than 1000 descendant Categories, an InvalidOperation error is returned.
The request is validated when the API receives it and again when the background process runs. If the change is no longer valid at that point, for example because the Stores of the parent Category changed or a referenced Store was deleted in the meantime, it isn't applied and no error is reported. All Categories in the subtree receive the same stores, so only the relation between the Category and its parent is validated.

Requests that change the Stores of the same subtree are processed in the order the background process receives them, which isn't necessarily the order they were sent in. Send the next request for the same subtree only after the previous change has been applied.

stores​
Value to set on the Category and each of its descendant Categories. It replaces the entire set of Stores assigned to each Category in the subtree.
If a Store doesn't exist, a ReferencedResourceNotFound error is returned.
If the Category has a parent Category that is assigned to Stores and stores contains a Store the parent isn't assigned to, an InvalidInput error is returned.
If the Category has a parent Category that is assigned to Stores and stores is empty, an InvalidInput error is returned.

Update actions

Add Asset

position​
Int​
Position in the array at which the Asset should be put. When specified, the value must be between 0 and the total number of Assets minus 1.
asset​

Value to append.

AssetDraftInput

key​
String​
name​
description​
custom​
sources​
Array of AssetSourceInput​
tags​
Array of String​

AssetSourceInput

uri​
String​
key​
String​
dimensions​
contentType​
String​

AssetDimensionsInput

width​
Int​
height​
Int​

Add Store

This action locks the Category and its parent Category. For details, see Category tree locking.
Value to add to the Category's stores.
When called through an in-Store endpoint, the caller must have permission for the referenced Store.

Change Asset Name

name​

New value to set. Must not be empty.

assetKey​
String​
New value to set. Either assetId or assetKey is required.
assetId​
String​
New value to set. Either assetId or assetKey is required.

Change Asset Order

This update action changes the order of the assets array. The new order is defined by listing the ids of the Assets.
assetOrder​
Array of String​
New value to set. Must contain all Asset ids.

Change Name

name​

New value to set. Must not be empty.

Change Order Hint

orderHint​
String​
New value to set. Must be a decimal value between 0 and 1. When sorted in ascending order, Categories with a lower orderHint appear before those with a higher value (for example, 0.05 before 0.07).

Change Slug

Changing the slug produces the CategorySlugChanged Message.
slug​
New value to set. Must not be empty. A Category can have the same slug for different Locales, but it must be unique across the Project. Valid slugs must match the pattern ^[A-Za-z0-9_-]{2,256}+$.

Change Parent

This action locks the entire Category tree in the Project for the duration of the request. For details, see Category tree locking.

New value to set as parent.

Remove Asset

assetKey​
String​
Value to remove. Either assetId or assetKey is required.
assetId​
String​
Value to remove. Either assetId or assetKey is required.

Remove Store

This action locks the Category and its parent Category. For details, see Category tree locking.

Every direct child Category must be assigned to at least one Store in that set; otherwise, the action is rejected.

  • When updating a Category via the general endpoint, all Stores can be removed as a global Category is accessible in all Stores.
  • When updating a Category via the Store-specific endpoint, you can remove the last Store only if at least one Store remains; otherwise, an InvalidOperation error is returned. If you do not have permission for the referenced Store, an InvalidInput error is returned.
Value to remove from the Category's stores.

Set Asset Custom Field

value​
String​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.
name​
String​
Name of the Custom Field.
assetKey​
String​
New value to set. Either assetId or assetKey is required.
assetId​
String​
New value to set. Either assetId or assetKey is required.

Set Asset Custom Type

typeId​
String​
typeKey​
String​
fields​
Array of CustomFieldInput​
assetKey​
String​
assetId​
String​

Set Asset Description

description​

Value to set. If omitted, any existing value is removed.

assetKey​
String​
New value to set. Either assetId or assetKey is required.
assetId​
String​
New value to set. Either assetId or assetKey is required.

Set Asset Key

Set or remove the key of an Asset.
assetKey​
String​

Value to set. If omitted, any existing value is removed.

assetId​
String​

Value to set.

Set Asset Sources

sources​
Array of AssetSourceInput​

Must not be empty. At least one entry is required.

Default: []​
assetKey​
String​
New value to set. Either assetId or assetKey is required.
assetId​
String​
New value to set. Either assetId or assetKey is required.

AssetSourceInput

uri​
String​
key​
String​
dimensions​
contentType​
String​

AssetDimensionsInput

width​
Int​
height​
Int​

Set Asset Tags

tags​
Array of String​

Keywords for categorizing and organizing Assets.

Default: []​
assetKey​
String​
New value to set. Either assetId or assetKey is required.
assetId​
String​
New value to set. Either assetId or assetKey is required.

Set Custom Field

name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Set Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Description

description​

Value to set. If omitted, any existing value is removed.

Set Key

key​
String​

Value to set. If omitted, any existing value is removed.

Set Meta Description

metaDescription​

Value to set.

Set Meta Keywords

metaKeywords​

Value to set.

Set Meta Title

metaTitle​

Value to set.

Set Stores

This action locks the Category and its parent Category. For details, see Category tree locking.

Every direct child Category must be assigned to at least one Store in that set; otherwise, the action is rejected.

  • When updating a Category via the general endpoint, all Stores can be removed as a global Category is accessible in all Stores.
  • When updating a Category via the Store-specific endpoint, the stores field cannot be empty; otherwise, an InvalidOperation error is returned.
    If you do not have permission for every Store currently assigned to the Category, an Unauthorized error is returned.
stores​
Value to set. It replaces the entire set of Stores assigned to the Category.
If the stores field contains a Store that you do not have permission for, an InvalidInput error is returned.

Set External ID

This update action sets a new ID that can be used as an additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP).

externalId​
String​

Value to set. If omitted, any existing value is removed.