Product Schema & Structure

SCAYLE provides you a very flexible product schema and entity level structure.
It allows you to model your product schema in a way that it matches your product portfolio you're planning to sell via SCAYLE.

Understand Product Hierachy

Products are the central data structure for category listings and product detail pages.
Information about products is stored as Attribute Groups. Product data can be configured and customized at different entity levels. The system differentiates between three entity levels: master, product, and variant.

• Masters: collections of products belonging together, sharing the highest level of attribute value (e.g., a specific t-shirt).
• Products: collections of variants belonging together, each sharing underlying similarities (e.g., color of the t-shirt).
• Variants: entities with the most specific representation of a product. These items carry stock and price info and are being sold in the shops (e.g., sneaker of specific brand > color: white > size: 42).
• Prices: entities defined on variant level and contain all information about prices, taxes and validity — upcoming prices can also be defined for automatic future price updates.

The user can specify which product information correlates to which entity level. Prices are determined by the variant because that is the specific entity to be sold.

Product Schema & Structure

You define your Product Schema by using Attribute Groups on Master, Product & Variant level.

Understand Attribute Groups

An Attribute Group is a collection of different attributes (or attribute values). For example, the Attribute Group color could contain attribute values; black, blue, and green. We use this information to define a product and its characteristics. All the information a customer may need to know about a product should be stored in an Attribute Group in SCAYLE. For example, if you want to share a product’s cleaning instructions, list the details as an attribute.

Simple and advanced Attribute Groups

There are two types of Attribute Group available in SCAYLE:

• simple attributes
• advanced attributes

Simple Attribute Groups can be used for different products, but it is also possible to add several values of a simple attribute group to one product with multi-select.

Advanced Attribute Groups are most often free text fields that are connected to a specific product.

Attribute Group Level

Every Attribute Group is valid for only one entity type, which is determined by the level.

The supported levels are:

• Master
• Product
• Variant
• Image
• Brand
• Category

Attribute Group Type

The Attribute Group type describes attribute values. The supported values are:

• simple: a string or a number, e.g., "red"
• simpleList: a list of simple values, e.g., ["red", "blue"]
• localizedString: a translatable text, e.g., {"de_DE": "Rot", "en_GB": "red"}
• localizedStringList: a list of localized strings, e.g., [{"de_DE": "Rot", "en_GB": "red"}, {"de_DE": "Blau", "en_GB": "blue"}]
• advanced: a compound value described by Attribute Group structure, e.g., {"width": 90, "height": 180, "unit": "cm"}
• advancedList: a list of advanced values, e.g., [{"width": 90, "height": 180, "unit": "cm""}, {"width": 100, "height": 200, "unit": "cm"}]

Shared Attributes

When an Attribute Group is defined as shared ("isShared": true), entities share attribute values instead of having their own values. In this case, if the value is changed or a new translation is added or removed for the attribute, all entities sharing the same attribute value will be affected.

Long attribute values

For attribute values with a string length longer than 255 characters, you have to create an advanced Attribute Group.

This can be done by passing "isShared": false and the respective Attribute Group type, for example localizedString if you want to have a translatable attribute.

See the example below for creating such an attribute group:

json

Copy

{
    "name": "description",
    "frontendName": {
        "en_US": "Description"
    },
    "type": "localizedString",
    "isShared": false,
    "level": "product"
}

Attribute Group Structure

Attributes of advanced and advancedList types are used to store compound arbitrary values. These values are described by the attribute group structure. For example, if you want to save product dimensions {"width": 90, "height": 180, "unit": "cm"}, you need the following structure:

json

Copy

{
    "width": {
        "type": "integer"
    },
    "height": {
        "type": "integer"
    },
    "unit": {
        "type": "attributeGroup",
        "attributeGroupName": "unit"
    }
}

The attribute group structure supports various data types:

• integer: for numbers
• text: for short text values
• longtext: for long text values
• date: for date values
• attributeGroup: for attribute values of the given group it requires attributeGroupName to be specified, e.g., {"type": "attributeGroup", "attributeGroupName": "unit"}
• attribute: for constant attribute values it requires attributeGroupName and attributeName to be specified, e.g., {"type": "attributeGroup", "attributeGroupName": "unit", "attributeName": "cm"}

Inconsistencies with the SCAYLE Panel

Attribute Structure

When creating an Attribute Group within the SCAYLE Panel, you can choose between Simple and Advanced attribute structures.

If Advanced is selected and Component has only one field, then Admin API considers this attribute group to be of the following type:

• simple - if the attribute group is not translatable and the field is a single-select
• simpleList - if the attribute group is not translatable and the field is a multi-select
• localizedString - if the attribute group is translatable and the field is a single-select
• localizedStringList - if the attribute group is translatable and the field is a multi-select

Nested Group Sets

Admin API does not support nested or multiple group sets in the advanced group structure.

What are master categories in SCAYLE?

Most shops offer a variety of products, so it's helpful to categorize these products. In SCAYLE, we use master categories, which could include divisions such as trousers, T-shirts, dresses, etc. Based on the master categories, you can define different product types (related to purchase categories in the tenant systems.) For example, differentiating between clothing products and furniture products. Every product requires a master category in SCAYLE, and you must input this information to create a product. Within each master category, you can define mandatory attribute groups for corresponding products.

Keep in mind the differences between master categories and shop categories. Master categories are only relevant for product structure in the SCAYLE backend.

You can set up master categories manually or by importing them in the SCAYLE Panel. We recommend manual setup because you’ll only need to complete this step once. Details can be found here.

Which attribute groups and master categories should you use?

Now that you have an overview of our product structure, you’ll need to decide what kinds of attribute groups and master categories you’ll need for your project.

We've put together this guide to help you with your decisions.

Admin API

Create Attribute Group

In SCAYLE, we distinguish between different attribute group types, in particular simple attributes with clearly defined single values, and advanced attributes with compound-structured values.

About this Method

The method is used to create an attribute group.

Method Signature

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.createAttributeGroup({}, {requestBody: newAttributeGroup});
let createdAttributeGroup = response.body;

Create a simple shared attribute group

JavascriptPHPcURLJava

Copy

let newAttributeGroup = {
    "name": "material",
    "frontendName": {
        "de_DE": "Material",
        "en_GB": "Material"
    },
    "group": "characteristics",
    "type": "simple",
    "isShared": true,
    "level": "product"
};

let response = await adminApi.apis.AttributeGroups.createAttributeGroup({}, {requestBody: newAttributeGroup});
let createdAttributeGroup = response.body;

Create an advanced attribute group

JavascriptPHPcURLJava

Copy

let newAttributeGroup = {
    "name": "material_composition_textile",
    "frontendName": {
        "de_DE": "Materialzusammensetzung",
        "en_GB": "Material Composition"
    },
    "type": "advancedList",
    "isShared": false,
    "level": "product",
    "structure": {
        "group": {
            "type": "attributeGroup",
            "attributeGroupName": "overmaterial"
        },
        "components": {
            "type": "array",
            "items": {
                "fraction": {
                    "type": "integer"
                },
                "unit": {
                    "type": "attribute",
                    "attributeGroupName": "unit",
                    "attributeName": "%"
                },
                "material": {
                    "type": "attributeGroup",
                    "attributeGroupName": "material"
                }
            }
        }
    },
    "shopCountries": [
        {
            "shopKey": "ms",
            "countryCode": "DE"
        }
    ],
    "isOverridablePerShop": true
};

let response = await adminApi.apis.AttributeGroups.createAttributeGroup({}, {requestBody: newAttributeGroup});
let createdAttributeGroup = response.body;

Delete Attribute Group

Please note that deletion of an attribute group is only possible if the following conditions below are fulfilled:

• The attribute group is not classified as a system attribute group.
• The attribute group contains no attributes that have ever been assigned to any entity.
• The attribute group is not used in the structure of any of the existing advanced attribute groups.
• The attribute group is not used in any of the existing configurations.

Additionally, please be aware that when an attribute group is deleted, all associated entities will also be removed.

About this Method

This method can be used to delete an existing attribute group.

Method Signature

JavascriptPHPcURLJava

Copy

adminApi.apis.AttributeGroups.deleteAttributeGroup({attributeGroupName: attributeGroupName});

Delete an Attribute Group

JavascriptPHPcURLJava

Copy

adminApi.apis.AttributeGroups.deleteAttributeGroup({attributeGroupName: "material_composition_textile"});

Update Attribute Group

Since attribute groups have many dependencies, there are some restrictions on when and how you can update them. Only an attribute group, which does not have any attributes can be updated. It is also not possible to change an attribute group level.

About this Method

This method can be used to update/replace an existing attribute group.

Method Signature

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.updateAttributeGroup({attributeGroupName: attributeGroupName}, {requestBody: attributeGroup});
let updatedAttributeGroup = response.body;

Replace an advanced attribute group with a simple one

JavascriptPHPcURLJava

Copy

let attributeGroup = {
    "name": "simple_material_composition_textile",
    "frontendName": {
        "de_DE": "Materialzusammensetzung",
        "en_GB": "Material Composition"
    },
    "group": "textile",
    "type": "simple",
    "isShared": true,
    "level": "product"
};

let response = await adminApi.apis.AttributeGroups.updateAttributeGroup({attributeGroupName: "material_composition_textile"}, {requestBody: attributeGroup});
let updatedAttributeGroup = response.body;

Update Attribute Group Frontend Name

About this Method

This method can be used to update/replace the frontend name for an existing attribute group.

Method Signature

JavascriptPHPcURLJava

Copy

await adminApi.apis.AttributeGroups.updateFrontendName({attributeGroupName: attributeGroupName}, {requestBody: attributeGroupFrontendName});

Update Frontend Name

JavascriptPHPcURLJava

Copy

let attributeGroupFrontendName = {
    "de": "Materialzusammensetzung",
    "en": "Material Composition"
};

await adminApi.apis.AttributeGroups.updateFrontendName({attributeGroupName: "material_composition_textile"}, {requestBody: attributeGroupFrontendName});

Get Attribute Group

You have the option to request attribute groups, both simple and advanced, by their names.

About this Method

This method can be used to get an existing attribute group by its name.

Method Signature

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.getAttributeGroup({attributeGroupName: attributeGroupName});
let attributeGroup = response.body;

Get an Attribute Group

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.getAttributeGroup({attributeGroupName: "simple_material_composition_textile"});
let attributeGroup = response.body;

Get Attribute Group Collection

When retrieving multiple attribute groups, you can paginate results and apply other parameters to narrow down your query.

About this Method

This method can be used to get a collection of attribute groups. It is possible to refine the search by applying filters in the options.

Method Signature

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.getAttributeGroups();
let attributeGroups = response.body.entities;

Options

Attribute group collection read can be used with optional parameters - called options:

Get attribute groups filtered by type

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.getAttributeGroups({"filters[type]": "simple"});
let attributeGroups = response.body.entities;

Get attribute groups filtered by level

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.getAttributeGroups({"filters[level]": "product"});
let attributeGroups = response.body.entities;

Get Attribute Collection

When retrieving multiple attributes, you can paginate results to limit your query.

About this Method

This method can be used to get a collection of shared attributes given for an attribute group.

Method Signature

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.getAttributes({attributeGroupName: attributeGroupName});
let attributes = response.body.entities;

Options

Get a list of 50 Attribute Groups

JavascriptPHPcURLJava

Copy

let response = await adminApi.apis.AttributeGroups.getAttributes({attributeGroupName: "material_composition_textile"}, {limit: 50});
let attributes = response.body.entities;

Example of Product Schema Definition for Fashion

For basic setup, we need to add the following attribute groups:

Create Attribute

This endpoint can be used to create an unattached attribute for an attribute group.

If Attribute Group is multiselect, only one option can be created per request.

Method Signature

JavaScriptPHPcURLJava

Copy

const response = await client.apis.AttributeGroups.createAttribute({attributeGroupName: attributeGroupName}, {requestBody: newAttribute});
const attribute = response.body;

Examples

Create non-localized attribute

JavaScriptPHPcURLJava

Copy

const attribute = {value: "XL"};
const response = await client.apis.AttributeGroups.createAttribute({attributeGroupName: "size"}, {requestBody: attribute});
const createdAttribute = response.body;

Create localized attribute

JavaScriptPHPcURLJava

Copy

const attribute = {value: {
    "de_DE" => "grün",
    "en_GB" => "green",
}};
const response = await client.apis.AttributeGroups.createAttribute({attributeGroupName: "color"}, {requestBody: attribute});
const createdAttribute = response.body;

Update Attribute

This endpoint can be used to update an attribute for an attribute group.

If Attribute Group is multiselect, only one option can be updated per request.

For a localized attribute, the translation for the default locale should be uses as {attributeValue} parameter.

Method Signature

JavaScriptPHPcURLJava

Copy

const response = await client.apis.AttributeGroups.updateAttribute({attributeGroupName: attributeGroupName, attributeValue: attributeValue}, {requestBody: newAttribute});
const attribute = response.body;

Examples

Update non-localized attribute

JavaScriptPHPcURLJava

Copy

const attribute = {value: "L"};
const response = await client.apis.AttributeGroups.updateAttribute({attributeGroupName: "size", attributeValue: "XL"}, {requestBody: attribute});
const updatedAttribute = response.body;

Update localized attribute

JavaScriptPHPcURLJava

Copy

const attribute = {value: {
    "de_DE" => "gelb",
    "en_GB" => "yellow",
}};
const response = await client.apis.AttributeGroups.updateAttribute({attributeGroupName: "color", attributeValue: "grün"}, {requestBody: attribute});
const updatedAttribute = response.body;

Delete Attribute

This endpoint can be used to delete an attribute from an attribute group.

If Attribute Group is multiselect, only one option can be deleted per request.

For a localized attribute, the translation for the default locale should be uses as {attributeValue} parameter.

Method Signature

JavaScriptPHPcURLJava

Copy

await client.apis.AttributeGroups.deleteAttribute({attributeGroupName: attributeGroupName, attributeValue: attributeValue});

Examples

Delete attribute

JavaScriptPHPcURLJava

Copy

await client.apis.AttributeGroups.deleteAttribute({attributeGroupName: "size", attributeValue: "XL"});

Update product state

Updating the product state will trigger the state evaluation. When the desired state is live, the product might end up in the problem state.

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Products.updateProductState({productIdentifier: productIdentifier}, {requestBody: productState});
let productState = response.body;

Update product's first live at

Update or create the time when products go live for the first time in a shop country.

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Products.updateProductsFirstLiveAt({}, {requestBody: productsFirstLiveAt});
let productsFirstLiveAt = response.body;

Storefront API

Use Storefront API to:

• Retrieve all Attribute Groups
• Get a specific Attribute Group

Product configuration

All product data is based on a predefined master data structure that is initially created and configured.

Once all product data has been transferred to the system, you can start with the master data configuration. The best way to do this is to get an overview in the Settings area.

On the left side, you can see the different data structure levels:

• Attributes: values that you assign to products provide detailed information
• Categories: determine the structure of assortments (as a tree structure) in the system
• Entity Overview: entities are the highest level of data structure: Master, Product, Variants, Media, Brand

Composite products

Composite products are generally considered to be the same as normal products. The difference is that composite products are not real products, but, as the name suggests, they are composed of several other products. Simple examples are a bikini top and a bikini pant or a jersey with a flocking (e.g. name and number) on the back. Here again the same product hierarchy applies, consisting of masters, products and variants.

If you want to read more about masters, products and variants, please refer to the corresponding pages, starting with Product Data Management - Products - Overview.

The data model being used to represent (composite) products in SCAYLE contains entities with multiple levels of abstractions.

• Masters: Collections of products belonging together, all sharing the highest level of attributes, e.g., t-shirt.
• Products: Collections of variants belonging together, each sharing underlying similarities, e.g., color.
• Variants: Entities with the most specific representation of a product. These items are being sold in the shops, e.g., sneaker of specific brand > color: white > size: 42).

Further education - SCAYLE Academy

Course

Import your products into SCAYLE

Introduction and preparation

• Product Data Management
• Tech

Robert Merten

VP Tech

Product Data Management

Import your products into SCAYLE

• Intermediate
• 6 lessons
• 1h 14m

Play tutorial