Queries and mutations for managing Categories in the platform.
Queries
Query Categories
| Arguments | |
|---|---|
whereString | |
sortArray of String | |
limitInt | |
offsetInt | |
Get Category
| Arguments | |
|---|---|
idString | Queries with specified ID |
keyString | Queries with specified key |
Mutations
Create Category
| Arguments | |
|---|---|
draft | |
storeKey | The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions. |
Update Category
| Arguments | |
|---|---|
versionLong | |
actionsArray of CategoryUpdateAction | |
storeKey | The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions. |
idString | Queries with specified ID |
keyString | Queries with specified key |
Delete Category
Output types
Category
idString | Unique identifier of the Category. |
keyString | User-defined unique identifier of the Category. |
versionLong | Current version of the Category. |
nameString | Name of the Category. |
nameAllLocalesArray of LocalizedString | Name of the Category. |
descriptionString | Description of the Category. |
descriptionAllLocalesArray of LocalizedString | Description of the Category. |
slugString | 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. |
slugAllLocalesArray 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. |
ancestorsRefArray of Reference | Contains the parent path towards the root Category. |
ancestorsArray of Category | Contains the parent path towards the root Category. |
parentRef | Parent Category of this Category. |
parent | Parent Category of this Category. |
orderHintString | 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). |
externalIdString | Additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP). |
metaTitleString | Name of the Category used by external search engines for improved search engine performance. |
metaTitleAllLocalesArray of LocalizedString | Name of the Category used by external search engines for improved search engine performance. |
metaKeywordsString | Keywords related to the Category for improved search engine performance. |
metaKeywordsAllLocalesArray of LocalizedString | Keywords related to the Category for improved search engine performance. |
metaDescriptionString | Description of the Category used by external search engines for improved search engine performance. |
metaDescriptionAllLocalesArray of LocalizedString | Description of the Category used by external search engines for improved search engine performance. |
stagedProductCountInt | Number of staged products in the category subtree. |
childCountInt | Number of direct child categories. |
childrenArray 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. |
assetsArray of Asset | Media related to the Category. |
storesRefArray 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. |
storesArray 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
Input types
CategoryDraft
keyString | 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. |
nameArray of LocalizedStringItemInputType | Name of the Category. |
descriptionArray of LocalizedStringItemInputType | Description of the Category. |
custom | Custom Fields for the Category. |
slugArray of LocalizedStringItemInputType | |
externalIdString | Additional identifier for external systems like customer relationship management (CRM) or enterprise resource planning (ERP). |
metaTitleArray of LocalizedStringItemInputType | Name of the Category used by external search engines for improved search engine performance. |
metaDescriptionArray of LocalizedStringItemInputType | Description of the Category used by external search engines for improved search engine performance. |
metaKeywordsArray of LocalizedStringItemInputType | Keywords related to the Category for improved search engine performance. |
orderHintString | 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 | Parent Category of the Category.
The parent can be set by its id or key. |
storesArray of ResourceIdentifierInput | Stores to assign the Category to.
|
assetsArray of AssetDraftInput | Media related to the Category. Default:[] |
AssetDraftInput
keyString | |
nameArray of LocalizedStringItemInputType | |
descriptionArray of LocalizedStringItemInputType | |
custom | |
sourcesArray of AssetSourceInput | |
tagsArray of String | |
type |
AssetSourceInput
uriString | |
keyString | |
dimensions | |
contentTypeString |
AssetDimensionsInput
widthInt | |
heightInt |
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
stores of the Category and to all of its descendant Categories.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.parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.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.
store | 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
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.
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.parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.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.
store | 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
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.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.parent for Categories in the subtree can fail and should be retried. For details, see Category tree locking.stores of the Category, an InvalidOperation error is returned. Other update actions in the same request are applied immediately.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.
storesArray of ResourceIdentifierInput | 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
positionInt | 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
keyString | |
nameArray of LocalizedStringItemInputType | |
descriptionArray of LocalizedStringItemInputType | |
custom | |
sourcesArray of AssetSourceInput | |
tagsArray of String | |
type |
AssetSourceInput
uriString | |
keyString | |
dimensions | |
contentTypeString |
AssetDimensionsInput
widthInt | |
heightInt |
Add Store
store | 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
nameArray of LocalizedStringItemInputType | New value to set. Must not be empty. |
assetKeyString | New value to set. Either assetId or assetKey is required. |
assetIdString | New value to set. Either assetId or assetKey is required. |
Change Asset Order
assets array. The new order is defined by listing the ids of the Assets.assetOrderArray of String | New value to set. Must contain all Asset ids. |
Change Name
nameArray of LocalizedStringItemInputType | New value to set. Must not be empty. |
Change Order Hint
orderHintString | 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
slugArray of LocalizedStringItemInputType |
Change Parent
parent | New value to set as parent. |
Remove Asset
assetKeyString | Value to remove. Either assetId or assetKey is required. |
assetIdString | Value to remove. Either assetId or assetKey is required. |
Remove Store
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.
store | Value to remove from the Category's stores. |
Set Asset Custom Field
valueString | 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. |
nameString | Name of the Custom Field. |
assetKeyString | New value to set. Either assetId or assetKey is required. |
assetIdString | New value to set. Either assetId or assetKey is required. |
Set Asset Custom Type
typeIdString | |
typeKeyString | |
type | |
fieldsArray of CustomFieldInput | |
assetKeyString | |
assetIdString |
Set Asset Description
descriptionArray of LocalizedStringItemInputType | Value to set. If omitted, any existing value is removed. |
assetKeyString | New value to set. Either assetId or assetKey is required. |
assetIdString | New value to set. Either assetId or assetKey is required. |
Set Asset Key
key of an Asset.assetKeyString | Value to set. If omitted, any existing value is removed. |
assetIdString | Value to set. |
Set Asset Sources
sourcesArray of AssetSourceInput | Must not be empty. At least one entry is required. Default:[] |
assetKeyString | New value to set. Either assetId or assetKey is required. |
assetIdString | New value to set. Either assetId or assetKey is required. |
AssetSourceInput
uriString | |
keyString | |
dimensions | |
contentTypeString |
AssetDimensionsInput
widthInt | |
heightInt |
Set Custom Field
nameString | Name of the Custom Field. |
valueString | 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
fieldsArray of CustomFieldInput | |
type | |
typeKeyString | |
typeIdString |
Set Description
descriptionArray of LocalizedStringItemInputType | Value to set. If omitted, any existing value is removed. |
Set Key
keyString | Value to set. If omitted, any existing value is removed. |
Set Meta Description
metaDescriptionArray of LocalizedStringItemInputType | Value to set. |
Set Meta Keywords
metaKeywordsArray of LocalizedStringItemInputType | Value to set. |
Set Meta Title
metaTitleArray of LocalizedStringItemInputType | Value to set. |
Set Stores
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
storesfield 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.
storesArray of ResourceIdentifierInput | 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).
externalIdString | Value to set. If omitted, any existing value is removed. |