Backend API: Create a category

Last updated:
Edit on GitHub

The categories resource of the Backend API lets Back Office integrations create categories in the category tree. This document describes how to create a category and which validations the request has to pass.

Installation

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

Create a category

To create a category, send the request:

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

Request sample: create a category

POST https://glue-backend.mysprykershop.com/categories

{
    "data": {
        "type": "categories",
        "attributes": {
            "categoryKey": "gaming-laptops",
            "parentCategoryKey": "computer",
            "templateName": "Catalog (default)",
            "isActive": true,
            "isInMenu": true,
            "isSearchable": true,
            "isClickable": true,
            "position": 5,
            "stores": ["DE", "AT"],
            "localizedAttributes": [
                {
                    "localeName": "en_US",
                    "name": "Gaming Laptops",
                    "metaTitle": "Gaming Laptops",
                    "metaDescription": "High-performance laptops",
                    "metaKeywords": "gaming, laptops"
                },
                {
                    "localeName": "de_DE",
                    "name": "Gaming-Laptops",
                    "metaTitle": "Gaming-Laptops",
                    "metaDescription": "Leistungsstarke Laptops",
                    "metaKeywords": "gaming, laptops"
                }
            ],
            "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
                        }
                    ]
                }
            ]
        }
    }
}
ATTRIBUTE TYPE REQUIRED DESCRIPTION
categoryKey String ✓ Unique key of the category. It becomes the resource id and cannot be changed later. Keys are matched case-insensitively, so a key that differs from an existing one only by case is rejected as a duplicate.
parentCategoryKey String ✓ unless isRoot is true Key of the parent category. The key is matched case-insensitively; the response contains the stored key.
templateName String ✓ Name of an existing category template. The name is case-sensitive.
localizedAttributes Array ✓ Localized attributes of the category. Provide at least one entry; each entry needs localeName and a non-empty name.
localizedAttributes.localeName String ✓ Name of an available locale—for example, en_US.
localizedAttributes.name String ✓ Name of the category in the locale. Must be unique among the categories on the same level. The category URL is generated from it.
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.
isRoot Boolean Set to true to create the root category. Only one root category can exist, and parentCategoryKey must be omitted. Default: false.
isActive Boolean Defines whether the category is active. Default: false.
isInMenu Boolean Defines whether the category is shown in the Storefront navigation menu. Default: true.
isSearchable Boolean Defines whether the category is searchable. Default: true.
isClickable Boolean Defines whether the category is clickable in the Storefront. Default: true.
position Integer Sort weight of the category among its siblings. Duplicates are allowed; setting it doesn’t renumber the siblings.
extraParentCategoryKeys Array Keys of additional parent categories. The keys are matched case-insensitively.
stores Array Names of existing stores to assign the category to.
imageSets Array Image sets of the category.
imageSets.localeName String Locale name of the image set. Omit it 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.
Localized attributes

The Back Office requires a name in every available locale. The API accepts a subset of locales, but a category without a name in a locale is not shown in the Back Office and in the Storefront for that locale, and it is not part of a name-sorted collection in that locale. Provide all locales unless you have a reason not to.

Response

Response sample: create a category 
{
    "data": {
        "id": "gaming-laptops",
        "type": "categories",
        "attributes": {
            "categoryKey": "gaming-laptops",
            "isActive": true,
            "isInMenu": true,
            "isSearchable": true,
            "isClickable": true,
            "templateName": "Catalog (default)",
            "parentCategoryKey": "computer",
            "position": 5,
            "extraParentCategoryKeys": [],
            "localizedAttributes": [
                {
                    "localeName": "en_US",
                    "name": "Gaming Laptops",
                    "metaTitle": "Gaming Laptops",
                    "metaDescription": "High-performance laptops",
                    "metaKeywords": "gaming, laptops",
                    "url": "/en/computer/gaming-laptops"
                },
                {
                    "localeName": "de_DE",
                    "name": "Gaming-Laptops",
                    "metaTitle": "Gaming-Laptops",
                    "metaDescription": "Leistungsstarke Laptops",
                    "metaKeywords": "gaming, laptops",
                    "url": "/de/computer/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 created and all failed checks are returned in the errors array.

STATUS CODE REASON
422 901 A required attribute is missing or has a wrong type—for example, categoryKey => This field is missing.
422 N/A A category with the specified categoryKey already exists.
422 N/A parentCategoryKey is missing and isRoot is not true.
422 N/A parentCategoryKey is provided together with isRoot: true.
422 N/A isRoot is true, but a root category already exists.
422 N/A The category specified in parentCategoryKey or extraParentCategoryKeys doesn’t exist.
422 N/A The template specified in templateName doesn’t exist. The available template names are listed in the error details.
422 N/A localizedAttributes is missing or empty, an entry has no localeName, or an entry has no name.
422 N/A A locale specified in localizedAttributes is not available.
422 N/A A store specified in stores doesn’t exist.
422 N/A A category with the same name already exists on the same level.
422 N/A The URL generated for a locale conflicts with an existing URL. The category is not created.

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