Shop Categories

General

Shop Categories help you to cluster your Assortment in multiple Categories and render your Categories as a Tree.
There is a m:n relation between Products & Shop Categories. So each Category can have multiple Products and each Product can be assigned to multiple Categories.

Category name & Path

Each category comes with a name and a path.
The category name is a localised string:

Copy

[
    'de_DE' => 'Kleider',
    'en_EN' => 'Dresses',
]

The category path gets automatically calculated by SCAYLE and represents a unique category identifier which can be used for lookups.
It contains the full path (including all parent category names) and looks like this:

Copy

/women/clothing/dresses

Status & Visibility of Shop Categories

Each Shop Category comes with two attribute values defining their Status & Visibility in the Storefront:

• isVisible - this attribute defines if the Storefront should render the Category to the Customer
• isActive - this attribute defines whether the Shop Category is active or inactive
• isExcludedFromSearch - This Attribute defines whether the Shop Category should be excluded from the search.

The Shop Category Status can be managed by the Shop Managers in the SCAYLE Panel.

Product Mapping via Product Sets

SCAYLE offers multiple ways to map the products to the corresponding shop categories:

• Explicitly include Products by their ID's
• Explicitly exclude Products by their ID's
• Include or exclude products using Shared Attributes on product or product master level
• Include only 'new' products
• Reference to the products of another shop category

Supported Filter for a Category

You can define the supported filter which can be used on a category page to filter products & do faceting.

Add additional data to your Shop Category

SCAYLE lets you define additional data on your Shop Category via Shop Category Properties.
This is useful for multiple reasons, just to highlight some:

• Add internal ID's or additional data to your category you need use in your Storefront
• Add SEO information to a category
• Add Category Descriptions / additional Content to your category
• Determine if the Shop Category is a sale-only category

Shop Category Properties allow you to store additional data to pre-defined keys.
Both - the key and the value must be a string.

Add a Shop Property Key

The definition of the Shop Category Property Key is done on SCAYLE instance level.
You can use the defined key on every shop within your instance.

JavaScriptPHPcURLJava

Copy

let shopCategoryPropertyKey = {
  "key": "sale",
  "isInheritable": true
};

let response = await adminApi.apis.ShopCategories.createShopCategoryPropertyKey({requestBody: shopCategoryPropertyKey});
let createdShopCategoryPropertyKey = response.body;

Update a Shop Category Property Key

Once you created a shop category property key, you can come back and update it later. However, you can only modify a key if it is currently not used within a shop category.

JavaScriptPHPcURLJava

Copy

let shopCategoryPropertyKey = {
    key: "new",
    isInheritable: true
};

let response = await client.apis.ShopCategories.updateShopCategoryPropertyKey(
    {shopCategoryPropertyKey: "sale"},
    {requestBody: shopCategoryPropertyKey}
);

let updatedShopCategoryPropertyKey = response.body;

Retrieve a Shop Category Property Key

You can request a shop category property keys by simply providing its name.

JavaScriptPHPcURLJava

Copy

let response = await client.apis.ShopCategories.getShopCategoryPropertyKey({shopCategoryPropertyKey: "sale"});
let shopCategoryPropertyKey = response.body;

Retrieve all Shop Category Property Keys for a Shop Category

If you would like to retrieve more than one shop category property key, you can fetch them all at once.

JavaScriptPHPcURLJava

Copy

let response = await client.apis.ShopCategories.getShopCategoryPropertyKeys();
let shopCategoryPropertyKeys = response.body.entities;

Add a Shop Property

After you created a Shop Category Property Key you can set the property value for a specific Shop Category.
In the example below we set the value 'NoSale' for the property key 'sale' for the Shop Category with the ID 1 within the Shop with the key 'ms' and the country code 'DE' (Germany):

JavaScriptPHPcURLJava

Copy

let shopCategoryProperty = {
    "key": "sale",
    "value": "NoSale"
};

let response = await adminApi.apis.ShopCategories.updateOrCreateShopCategoryProperty({shopKey: "ms", countryCode: "DE", shopCategoryId: 1}, {requestBody: shopCategoryProperty});
let updatedShopCategoryProperty = response.body;

Update or add a Shop Property

If you want to update a shop property or add it - in case it doesn't exist - you can use the updateOrCreateProperty method:

JavaScriptPHPcURLJava

Copy

let shopCategoryProperty = {
    "key": "sale",
    "value": "NoSale"
};

let response = await adminApi.apis.ShopCategories.updateOrCreateShopCategoryProperty({shopKey: "ms", countryCode: "DE", shopCategoryId: 1}, {requestBody: shopCategoryProperty});
let updatedShopCategoryProperty = response.body;

Delete Shop Category property value

In case you want to remove the value for a saved Shop Category Property for a specific key you can use the deleteProperty method:

PHPcURLJavaJava Script

Copy

$adminApi->shopCategories->deleteProperty('ms', 'DE', 1, 'sale');

Retrieve a Shop Category Properties for a Shop Category

If you want to request a shop category property, you need to provide its respective category ID and property key.

JavaScriptPHPcURLJava

Copy

let response = await client.apis.ShopCategories.getShopCategoryProperty({shopKey: "ms", countryCode: "DE", shopCategoryId: 1, shopCategoryPropertyKey: "sale"});
let shopCategoryProperty = response.body;

Retrieve all Shop Category Properties for a Shop Category

You can retrieve all shop category properties for a specific shop category. In this case you don't pass any property key to the call:

PHPcURLJavaJava Script

Copy

$shopCategoryPropertyCollection = $adminApi->shopCategories->allProperties('ms', 'DE', 1);

Shared Category Tree

If you work with multiple Shop Countries (e.g. Shop.com with a dutch and a german shop country) you normally manage the category tree only once.
SCAYLE offers you multiple features to make the shop category handling in such a scenario very efficient.
The general shop category tree is shared across all shops, but you can change the following settings on shop country level:

• Visibility of categories
• Active-Status
• Name (for translation reasons / localisation)
• Shop Properties

If you still want to have a dedicated shop category tree for a shop country you have to set a new categoryTreeId when you create the shop country, as documented here.

Manage Shop Categories

Shop Categories represent a nested category tree. Each node holds it's own product set. So the parent category node does not contain the products of it's children by default. If you want to enable this behavior you need to make sure that a parent category node contains all product set configurations of it's children.

To manage Shop Categories you need to work with the Admin API.

Create a shop category

The most minimal way to create a new shop category for the shop with the shop key 'ms' looks like this:

JavaScriptPHPcURLJava

Copy

let shopCategory = {
    "name": {
        "en_EN": "New shop category"
    },
    "isActive": true,
    "isVisible": true,
    "isExcludedFromSearch": false
};

let response = await adminApi.apis.ShopCategories.createShopCategory({shopKey: "ms"}, {requestBody: shopCategory});
let createdShopCategory = response.body;

Shop category parameters

ShopCategoryCountry

ShopCategoryProperty

When creating a shop category, it is important to keep the following details in mind:

• leftSiblingId is only used to determine a new category position. The category will be inserted after the given left sibling category.
• The category path is automatically calculated based on the category name and the category's parents. This operation is asynchronous and can be executed with a delay. This is the reason why the countries.path field might not be present in the response.
• isActive, isVisible, and properties will be propagated to all existing shop countries if specified. It is important to note that new shop countries will not automatically receive these values. You have to create a new configuration each time a shop country is created.
• The deactivation of a parent category by setting the isActive flag to false will also deactivate its child categories. Activating a child category will activate all respective parent categories.
• It is recommended to create shop countries beforehand to avoid manual creation of shop-specific configs.
• There is one reserved property with a special meaning: sale. It allows you to include or exclude discounted products in the assortment by setting the value respectively to Sale or NoSale.
• A shop category is created along with shop country-specific settings. The category gets a localized name for every existing country. If name has a translation that matches the country's language, then this value is used as a category name. Otherwise, the default language translation is used as a country specific name.

If there exists a custom data configuration for the shopCategory entity and the custom data isn't provided within the create request, the defaultValue specified in the custom data configuration for each property would be considered.

Create a shop category with a shop property

It's possible to directly add some shop properties to a shop category create call:

JavaScriptPHPcURLJava

Copy

let shopCategory = {
    "name": {
        "de_DE": "New Shop Category"
    },
    "isActive": true,
    "isVisible": true,
    "properties": [
        {
            "key": "sale",
            "value": "NoSale"
        }
    ]
};

let response = await adminApi.apis.ShopCategories.createShopCategory({shopKey: "ms"}, {requestBody: shopCategory});
let createdShopCategory = response.body;

Create a nested shop category

The attribute 'parentId' defines the parent category id.
You can create a category 'Apparel' and a child-category 'Dresses' with the following code:

JavaScriptPHPcURLJava

Copy

let apparelShopCategory = {
    "name": {
        "en_EN": "Apparel"
    },
    "isActive": true,
    "isVisible": true
};

let response = await adminApi.apis.ShopCategories.createShopCategory({shopKey: "<shop-key>"}, {requestBody: apparelShopCategory});
let createdApparelCat = response.body;

let dressesShopCategory = {
    "name": {
        "de_DE": "New Shop Category"
    },
    "isActive": true,
    "isVisible": true,
    "parentId": createdApparelCat.id
};

let response = await adminApi.apis.ShopCategories.createShopCategory({shopKey: "<shop-key>"}, {requestBody: dressesShopCategory});
let createdDressesCat = response.body;

Create a nested shop category with a category sorting

In case you have multiple shop categories on the same hierarchy level you typically want to define the sorting of the category nodes.
This can be done by using the 'leftSiblingId' property. The new Category 'Dresses' will be inserted after the given left sibling category (in the example below category with ID 100).

JavaScriptPHPcURLJava

Copy

let shopCategory = {
    "name": {
        "en_EN": "Dresses"
    },
    "isActive": true,
    "isVisible": true,
    "leftSiblingId": 100
};

let response = await adminApi.apis.ShopCategories.createShopCategory({shopKey: "<shop-key>"}, {requestBody: shopCategory});
let createdDressesCat = response.body;

Create a new shop category with a product set definition

JavaScriptPHPcURLJava

Copy

let shopCategory = {
    "parentId": 1,
    "leftSiblingId": 2,
    "name": {
        "en_EN": "Red Products Category"
    },
    "productSets": [
        {
            "isNew": true,
            "attributes": [
                {
                    "name": "color",
                    "include": ["red"]
                }
            ]
        },
        {
            "referencedProductSetId": 1,
            "includeProductIds": [1, 2]
        },
        {
            "excludeProductIds": [4]
        }
    ],
    "isActive": true,
    "isVisible": true,
    "properties": [
        {
            "key": "sale",
            "value": "NoSale"
        }
    ]
};

let response = await adminApi.apis.ShopCategories.createShopCategory({shopKey: "ms"}, {requestBody: shopCategory});
let createdShopCategory = response.body;

Update a Shop Category

To update a shop category SCAYLE offers a update method:

JavaScriptPHPcURLJava

Copy

let shopCategory = {
     "name": {
        "en_EN": "Sneaker"
    }
};

let response = await adminApi.apis.ShopCategories.updateShopCategory({shopKey: "ms", shopCategoryId: 1}, {requestBody: shopCategory});
let updatedShopCategory = response.body;

Referencing Product Sets

If a shop category was initially created with a product set that references another product set via the 'referencedProductSetId' attribute and this reference is not sent again in the update request, the reference is removed.

Get a shop category

You can get a shop category and select the additional information & data which should be returned for the selected shop category.

The following options are available for the 'with' paramter:

• countries
• countries.properties
• countries.customData
• customData

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.ShopCategories.getShopCategory({shopKey: "ms", shopCategoryId: 1, with: "countries"});
let shopCategory = response.body;

Get multiple shop categories

To fetch multiple shop categories SCAYLE offers you pagination and filtering.

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.ShopCategories.getShopCategories({shopKey: "shopKey"});
let shopCategoryCollection = response.body.entities;

Options:

Delete a shop category

You can delete a shop category. In this case all children also will get deleted.

JavaScriptPHPcURLJava

Copy

adminApi.apis.ShopCategories.deleteShopCategory({shopKey: shopKey, shopCategoryId: shopCategoryId});

Deletion effect on Product Sets

Direct and indirect incoming references (if any) will be deleted without copying conditions over.

Unlink Referencing Product Sets

This method can be used to unlink a product set from the referencing product sets. It is possible to copy conditions of the reference to the product sets from which it will be unlinked.

Method Signature

JavaScriptPHPcURLJava

Copy

client.apis.ShopCategories.unlinkReferencingProductSets({shopKey: shopKey, productSetId: productSetId}, {requestBody: productSetUnlinkInstruction});

Product Set Unlink Instruction Entity

Details

Copying conditions

If you want to unlink a product set but preserve its conditions (e.g. excluded or included product ids), you need to set copyConditions = true. In this case, all conditions defined for the unlinked reference product set will be copied to the product set IDs provided in the payload.

Examples

Unlink Referenced Product Sets

JavaScriptPHPcURLJava

Copy

let productSetUnlinkInstruction = {
    productSetIds: [10, 22],
    copyConditions: true
};

client.apis.ShopCategories.unlinkReferencingProductSets({shopKey: "ms", productSetId: 1}, {requestBody: productSetUnlinkInstruction});

Use Shop Categories in your Storefront

To fetch the Shop Categories in your Storefront you need to work with the Storefront API.

Get a category tree

If you are not working with a specific child category yet, root categories are used to access the whole category tree. Usually the category tree makes a fundamental part of the navigation in an online shop.

Furthermore, there are certain parameters (such as name, slug, path, and description) that are used by default when requesting a category.

Categories are related by parentId and childrenIds.

Get the full category tree

We can use a shop category tree for the navigation in our shop.

TypescriptPHPcURL

Copy

// Get full category tree 
const categories = await client.categories.getRoots({
  with: { children: 1 },
});

for (const category of categories) {
  console.log(category.name)
}

By default each category comes with its childrenIds. But to iterate through our category tree and to build a link structure we need to ask for the fields of the children categories, e.g. name, slug or even their children. To do so, we pass children as our with parameter.

Get a single category

Retrieve a shop category by ID or path with parent and child categories.

Categories are stored in a tree structure. Using this API, any individual category can be requested. Additionally, it is possible to include its parents (recursively) and children.

You can query a single category by specifying its ID or path. A path consists of the category's slug prepended with the slugs of its parent up to the root category.

Example: Get a category by ID

We know the category ID of 'Women' is 6. To simply get the category's own properties we just have to pass the ID as parameter.

TypescriptPHPcURL

Copy

const category = await client.categories.getById(6, {});
console.log(category.name)

Example: Get a category by ID with their parent

In this example we query the category "Shirts", id 8, and also all its parent categories which are "Women" and "Clothing".

TypescriptPHPcURL

Copy

const category = await client.categories.getById(6, {
  with: { parents: 'all' }, 
});

console.log(category.name)
console.log(category.parent?.name)

Example: Get category by ID with its children

In the previous example we saw that our category "Women" has a field childrenIds. Of course we could now look up each of these categories with a dedicated requests. We could also request them all by their IDs in a single second request, see this example. But instead we are going to safe these extra requests and include all children by specifying them as with parameter.

TypescriptPHPcURL

Copy

const category = await client.categories.getById(6, {
  with: { children: 1 }, 
});

console.log(category.name)
console.log(category.children?.length)

Example: Get a category by path

You can also query a category by its path instead of its ID.

TypescriptPHPcURL

Copy

const category = await client.categories.getByPath(
  ["women", "clothing", "shirts"],
);

console.log(category.name);

Get multiple categories

It's possible to retrieve multiple shop categories by their IDs. Useful when you have a single category page and want to tease and link to it's children.

Example: Get Categories with their Children

This time we are on one of our root categories, "Women". We already know their childrenIds from our previous data request in this example.

Now we want to know more about our children categories. So we pass their ids as a parameter. Also we set the depth to get the properties of their children as well.

TypescriptPHPcURL

Copy

// Get properties of multiple categories plus their children
const childrenIds = [7, 9, 10];
const categories = await client.categories.getByIds(childrenIds, {
  with: {
    absoluteDepth: 2,
  },
});

console.log(categories[0].name);
console.log(categories[0].children[0].name);
// => Clothing
// => Shirts

Get Categories with their parents

Sometimes we also want to get information about the parents of our categories.

In this example we request information about two shirt categories.

They are similar and even belong to parent categories with the same name. But they are different. One is a child of Men, the other one a child of Women.

To get the parent we pass it in the with parameter.

TypescriptPHPcURL

Copy

// Get properties of multiple categories plus their parents
const childrenIds = [3, 8];
const categories = await client.categories.getByIds(childrenIds, {
  with: {
    parents: "all",
  },
});

console.log(categories[0].parent.parent.name);
console.log(categories[1].parent.parent.name);
// => Men
// => Women

Response

json

Copy

[
    {
        "id": 3,
        "path": "/men/clothing/shirts",
        "name": "Shirts",
        "slug": "shirts",
        "description": "",
        "parentId": 2,
        "rootlineIds": [1, 2, 3],
        "childrenIds": [],
        "properties": [],
        "isHidden": false,
        "depth": 3,
        "supportedFilter": [],
        "parent": {
            "id": 2,
            "path": "/men/clothing",
            "name": "Clothing",
            "slug": "clothing",
            "description": "",
            "parentId": 1,
            "rootlineIds": [1, 2],
            "childrenIds": [3],
            "properties": [],
            "isHidden": false,
            "depth": 2,
            "supportedFilter": [],
            "parent": {
                "id": 1,
                "path": "/men",
                "name": "Men",
                "slug": "men",
                "description": "",
                "parentId": 0,
                "rootlineIds": [1],
                "childrenIds": [2, 4, 5],
                "properties": [],
                "isHidden": false,
                "depth": 1,
                "supportedFilter": [],
                "shopLevelCustomData": {},
                "countryLevelCustomData": {}
            },
            "shopLevelCustomData": {},
            "countryLevelCustomData": {}
        },
        "shopLevelCustomData": {},
        "countryLevelCustomData": {}
    },
    {
        "id": 8,
        "path": "/women/clothing/shirts",
        "name": "Shirts",
        "slug": "shirts",
        "description": "",
        "parentId": 7,
        "rootlineIds": [6, 7, 8],
        "childrenIds": [],
        "properties": [],
        "isHidden": false,
        "depth": 3,
        "supportedFilter": [],
        "parent": {
            "id": 7,
            "path": "/women/clothing",
            "name": "Clothing",
            "slug": "clothing",
            "description": "",
            "parentId": 6,
            "rootlineIds": [6, 7],
            "childrenIds": [8],
            "properties": [],
            "isHidden": false,
            "depth": 2,
            "supportedFilter": [],
            "parent": {
                "id": 6,
                "path": "/women",
                "name": "Women",
                "slug": "women",
                "description": "",
                "parentId": 0,
                "rootlineIds": [6],
                "childrenIds": [7, 9, 10],
                "properties": [],
                "isHidden": false,
                "depth": 1,
                "supportedFilter": [],
                "shopLevelCustomData": {},
                "countryLevelCustomData": {}
            },
            "shopLevelCustomData": {},
            "countryLevelCustomData": {}
        },
        "shopLevelCustomData": {},
        "countryLevelCustomData": {}
    }
]

Get products count for all categories

You can retrieve the products count for all categories using our Filters Endpoint. Categories which don't have any product assigned to them will not be returned.

You are also able to pass filters to the endpoint to be able to check which categories have products in combination with the filters.

Example: Get categories with products matching a maximum price

In this example, all categories with products having a maximum price of 10 euros are returned.

TypescriptcURL

Copy

const categories = await client.filters.getValues('categoryIds', {
  where: {
    maxPrice: 1000,
  },
});

for (const category of categories) {
  console.log(category)
}

Response

json

Copy

[
  {
    "id": 1,
    "productCount": 10
  },
  {
    "id": 2,
    "productCount": 20
  },
]

Further education - SCAYLE Academy

Course

Getting Started With SCAYLE

Create Shop Categories

• Getting started
• Tech

Robert Merten

VP Tech

Getting Started

Getting Started With SCAYLE

• Beginner
• 10 lessons
• 1h 55m

Play tutorial