Backend API: Update a category

Last updated:
Edit on GitHub

The categories resource of the Backend API lets Back Office integrations update categories, including moving them in the category tree and reordering them among their siblings. This document describes how to update a category.

Installation

The endpoints are provided by the Category and ProductCategory modules. For details on installing the category capability, see Install the Category Management feature.

Update a category

To update a category, send the request:

PATCH /categories/{{category_key}}

PATH PARAMETER DESCRIPTION
{{category_key}} Key of the category to update. The key is matched case-insensitively. To get it, retrieve categories.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.

The update is partial: attributes you omit keep their stored values. Attributes that hold a list behave as follows:

  • localizedAttributes: entries are merged by localeName. An entry updates only the fields it contains; locales you omit stay untouched.
  • extraParentCategoryKeys, stores, imageSets: the stored list is replaced with the provided one. Omit the attribute to keep the stored list; send an empty array to remove all entries.

Request sample: move a category under another parent and update its attributes

PATCH https://glue-backend.mysprykershop.com/categories/gaming-laptops

{
    "data": {
        "type": "categories",
        "id": "gaming-laptops",
        "attributes": {
            "parentCategoryKey": "notebooks",
            "position": 1,
            "isActive": false,
            "localizedAttributes": [
                {
                    "localeName": "en_US",
                    "metaTitle": "Gaming Laptops and Notebooks"
                }
            ]
        }
    }
}
ATTRIBUTE TYPE REQUIRED DESCRIPTION
parentCategoryKey String Key of the new parent category. A new value moves the category with its whole subtree under the new parent and regenerates the category URLs. The key is matched case-insensitively. The category itself and its descendants are not allowed as the parent. The root category cannot be moved.
position Integer New sort weight of the category among its siblings. Use it to reorder categories on one level.
templateName String Name of an existing category template. The name is case-sensitive.
isActive Boolean Defines whether the category is active.
isInMenu Boolean Defines whether the category is shown in the Storefront navigation menu.
isSearchable Boolean Defines whether the category is searchable.
isClickable Boolean Defines whether the category is clickable in the Storefront.
localizedAttributes Array Localized attributes to update, merged by localeName. Changing name regenerates the category URL in that locale.
extraParentCategoryKeys Array Keys of the additional parent categories. Replaces the stored list.
stores Array Names of the stores the category is assigned to. Replaces the stored list.
imageSets Array Image sets of the category. Replaces the stored list.

categoryKey and isRoot cannot be changed.

Response

Response sample: update a category 
{
    "data": {
        "id": "gaming-laptops",
        "type": "categories",
        "attributes": {
            "categoryKey": "gaming-laptops",
            "isActive": false,
            "isInMenu": true,
            "isSearchable": true,
            "isClickable": true,
            "templateName": "Catalog (default)",
            "parentCategoryKey": "notebooks",
            "position": 1,
            "extraParentCategoryKeys": [],
            "localizedAttributes": [
                {
                    "localeName": "en_US",
                    "name": "Gaming Laptops",
                    "metaTitle": "Gaming Laptops and Notebooks",
                    "metaDescription": "High-performance laptops",
                    "metaKeywords": "gaming, laptops",
                    "url": "/en/computer/notebooks/gaming-laptops"
                },
                {
                    "localeName": "de_DE",
                    "name": "Gaming-Laptops",
                    "metaTitle": "Gaming-Laptops",
                    "metaDescription": "Leistungsstarke Laptops",
                    "metaKeywords": "gaming, laptops",
                    "url": "/de/computer/notebooks/gaming-laptops"
                }
            ],
            "stores": [
                "DE",
                "AT"
            ],
            "imageSets": [
                {
                    "localeName": "en_US",
                    "name": "default",
                    "images": [
                        {
                            "externalUrlSmall": "https://images.example.com/gaming-s.jpg",
                            "externalUrlLarge": "https://images.example.com/gaming-l.jpg",
                            "sortOrder": 0
                        }
                    ]
                }
            ],
            "isRoot": false
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/categories/gaming-laptops"
        }
    }
}
ATTRIBUTE TYPE DESCRIPTION
categoryKey String Unique key of the category. It is also the resource id.
uuid String Universally unique identifier of the category. Read-only. It is null on installations that do not have the optional uuid column, and on categories created before it was introduced until uuid:generate Category spy_category has been run for them. categoryKey, not uuid, is the resource id.
isActive Boolean Defines whether the category is active.
isInMenu Boolean Defines whether the category is shown in the Storefront navigation menu.
isSearchable Boolean Defines whether the category is searchable.
isClickable Boolean Defines whether the category is clickable in the Storefront.
templateName String Name of the category template.
parentCategoryKey String categoryKey of the parent category. null for the root category.
position Integer Sort weight of the category among its siblings. Siblings are ordered by this value in ascending order.
extraParentCategoryKeys Array categoryKey values of the additional parent categories.
localizedAttributes Array Localized attributes of the category, one entry per locale.
localizedAttributes.localeName String Locale name—for example, en_US.
localizedAttributes.name String Name of the category in the locale.
localizedAttributes.metaTitle String Meta title of the category in the locale.
localizedAttributes.metaDescription String Meta description of the category in the locale.
localizedAttributes.metaKeywords String Meta keywords of the category in the locale.
localizedAttributes.url String URL of the category in the locale. It is generated from the category name and the parent categories.
stores Array Names of the stores the category is assigned to.
imageSets Array Image sets of the category.
imageSets.localeName String Locale name of the image set. null for the default image set.
imageSets.name String Name of the image set.
imageSets.images Array Images of the image set.
imageSets.images.externalUrlSmall String URL of the small image.
imageSets.images.externalUrlLarge String URL of the large image.
imageSets.images.sortOrder Integer Order of the image within the image set.
isRoot Boolean Defines whether the category is the root category.

Possible errors

The request is validated as a whole: if any check fails, nothing is updated and all failed checks are returned in the errors array.

STATUS CODE REASON
404 N/A The category with the specified key doesn’t exist.
422 901 An attribute has a wrong type.
422 N/A categoryKey differs from the key of the category. The key cannot be changed.
422 N/A isRoot differs from the stored value. The root status cannot be changed.
422 N/A parentCategoryKey is provided for the root category. The root category cannot be moved.
422 N/A The category specified in parentCategoryKey or extraParentCategoryKeys doesn’t exist.
422 N/A The category specified in parentCategoryKey or extraParentCategoryKeys is the category itself or one of its descendants.
422 N/A The template specified in templateName doesn’t exist. The available template names are listed in the error details.
422 N/A A locale specified in localizedAttributes is not available, or an entry has no localeName.
422 N/A A store specified in stores doesn’t exist.
422 N/A A category with the same name already exists on the target level.

| 401 | N/A | The Authorization header is missing, or the access token is invalid or expired. | | 403 | N/A | The authenticated Back Office user is not allowed to access the categories resource. |

To view generic errors and status codes of the Backend API, see Backend API request and response reference.