Creating Shop Categories

In this section, we’ll cover the basic aspects of how to use the Storefront API on the homepage and for navigation. Additionally, we'll explore the creation and management of shop categories, an important part of product organization.

Creating Shop Categories in SCAYLE Panel

Shop categories in the SCAYLE Panel are crucial for structuring product relationships and organizing your storefront. Each category can be assigned any number of filters, making each one unique and recognizable to your customers. The purpose of categories is to simplify navigation in the storefront, creating a well-structured and organized way of presenting products.

By default, the category trees defined for each shop country can also be used as storefront navigation menus in the header section. If you need a customizable navigation structure independent of the shop country category tree, try using this feature.

Creating new shop categories

After setting up the German and Swiss Fashion Store shops, defining and importing product data, and configuring warehouses, it's time to create shop categories. In the following section, we'll create a global category tree with the first shop category being "men." Then, we’ll create the subcategories "trousers" and "shirts." We'll also specify which products will be displayed in each category and which filters we can apply.

Create shop categories

Click on "shops" in the navigation.
Select your shop.
Open the “products” dropdown in the side navigation.
Select "categories."

The category tree we’re setting up will be shared across all shop countries.
You’ll have the option to customize the visibility and state (activated/deactivated) of specific shop categories for each shop country later on.

Create the shop category “men”

Click on new category and enter the shop category name.
Click on next.

Creating a global category.

Category specification

In the “included product” section, we'll decide which products to display. You can either include or exclude certain product IDs or define criteria for the product set based on master categories and attribute groups.

We'll focus on the product set, skipping the inclusion or exclusion of specific product IDs.
We'll select the master category as the criterion for the product set.
Adding master category to global category.
Select the master categories we created earlier: “T-shirts” and “trousers.”
Save.

Next, you’ll need to select at least one filter to create a shop category. Once you assign a simple attribute group to a filter, customers can use it on the shop’s frontend to filter the category pages.

Click on "add first filter.""
Select "brand" as the filter.
Continue to select "color" and "size" as additional filters.
Save.

Adding filter to global category.

Repeat the steps outlined above to create the "shirts" and "trousers" subcategories.

Created category with subcategory.

[note] Congratulations! You’ve just created your first global shop categories! [/note]

[tip] To view the products added to your category click “more” on the shop country level. This will open a new tab displaying the relevant product list.

Please note that general adjustments to the category (such as filters, included products, and category name) can only be made on the shared category tree. You can learn more about how to copy categories or change the order of the category tree here. [/tip]

Adjusting the shop country category tree

Next, we'll adjust the global category tree to meet the requirements of the German and Swiss shop countries. Let's assume that the German Fashion Store wants to highlight the "men" category and the "shirts" subcategory in the storefront's navigation menu. The "trousers" subcategory will be active but is hidden in the navigation. In Switzerland, the category tree will look almost the same, but the "trousers" subcategory will be inactive.

By default, all newly created categories are inactive (shown in red), meaning that customers won’t be able to find them in the shop. If categories are displayed in green, they are active and therefore can be found in the shop as well as in the navigation. If categories are green and transparent, customers can access them via URLs, but they won't be visible in the navigation.

Let's configure the categories:

Select “Germany” in the shop country dropdown menu in the side navigation (located at the top of the side navigation.)
Open the category “men.”
1. Click on the three dots.
2. Select “make active” and confirm.
Select the “shirts” subcategory.
1. Click on the three dots.
2. Select “make active” and confirm.
Click on the “trousers” subcategory.
1. Click on the three dots.
2. Select “make active” and confirm.
3. Click on “make invisible” and confirm.

Activating subcategory Shirts.

Activated and hidden subcategories.

Now, let's follow the same steps for the Swiss shop country, with one key difference–the “trousers” category will remain inactive. After completing these steps, your final result should look like this:

Inactive subcategory.

[note] Great job! You’ve just created your first shop country categories! [/note]

Deleting categories

You can only delete a category from the category tree at the global level, not at the shop country level. However, on a shop country level, you can set a category to be "inactive" and "hidden." To delete a category globally which will affect all shop countries, follow these steps:

Open the shared category tree by selecting all countries in the shop country dropdown in the side menu.
Select a category, e.g. subcategory “trousers.”
A confirmation screen will appear.
Enter the category’s name: “trousers.”
Mark the checkbox for the confirmation statement.
Click on the “delete trousers” button.

Delete Categories.

Well done! You are now able to adjust global and shop country category trees!

In this section, we’ll briefly cover the most important endpoints and best practices. Shop categories structure the shop assortment and provide additional information using specific properties. Find more on this topic here.

Retrieve root categories and their children in a tree structure

What is this endpoint for?

The bapiClient.categories.getRoots function returns a list of root-level categories, including all its children if required. To retrieve a hidden category, you can include the parameter includeHidden: true.

The Storefront Core provides a function called getRootCategories(...). This function fetches the data from Storefront Core API and additionally maps it to an object containing the categories and an activeNode property.

The underlying API call fetches the root categories by utilizing the “categoryByPath” endpoint:

https://BAPI_HOST/categories?with=variants:all,attributes:all&campaignKey=CAMPAIGN_KEY

The path being /.

The Storefront Core uses Redis caching for performance optimization. The Redis key set by the SFC is prefixed with root-categories appended with the request hash. To view the data in your cache, use this cache key.

Here’s an example of SFC:

  if (path === '/') {
    return getRootCategories({ children, includeHidden }, ...)
  }

The data retrieved from the Storefront Core might look something like this:

{
    categories: [{
        "id": 2045,
        "path": "/women",
        "name": "Women",
        "slug": "women",
        "description": "",
        "parentId": 0,
        "rootlineIds": [
            2045
        ],
        "childrenIds": [],
        "properties": [],
        "isHidden": false,
        "depth": 1,
        "supportedFilter": [
            "color",
            "size",
            "brand",
            "material"
        ],
        "shopLevelCustomData": {},
        "countryLevelCustomData": {},
        "children": []
    },...],
    activeNode: undefined,
  }

Retrieve multiple shop categories with their parent and children

What is this endpoint for?

The bapiClient.categories.getById function returns a single category along with all its parents and children, if needed. To retrieve a hidden category, you can pass includeHidden: true.

SFC (Storefront Core) provides a function called getCategoryById(...) in useCategories(...), which returns the data from Storefront Core API without any modification.

Here is an example using Storefront Core:

const {
  getCategoryById,
} = useCategories('some-global-key')

onFetchAsync(async () => {
  const category = await getCategoryById(1337)
  if (!category) throw new Error('Category not found!')
})

The data comes straight from Storefront API, with no modifications happening in SFC.

{
   "id": 2045,
   "path": "/women",
   "name": "Women",
   "slug": "women",
   "description": "",
   "parentId": 0,
   "rootlineIds": [
      2045
   ],
   "childrenIds": [],
   "properties": [],
   "isHidden": false,
   "depth": 1,
   "supportedFilter": [
      "color",
      "size",
      "brand",
      "material"
   ],
   "shopLevelCustomData": {},
   "countryLevelCustomData": {},
   "children": []
}

Dev-to-Dev Hint

We recommend using getByPath as it's easier for debugging. Instead of passing an ID, you’d pass the unique category path. For example, /men/clothing instead of 2052.

category ID could vary for different environments like integration, staging, and production.

Example

If a URL from the CMS (Content Management System) contains an ID instead of a path, we can resolve it using the getById method and return the corresponding path.

const match = url.match(/\/categories\/(\d+)/)
if (!match) return
const [type, _id] = match
const id = parseInt(_id, 10)

return (
  await context.cached(context.bapiClient.categories.getById)(id)
).path