docs
  1. Core-documentation
  2. The Basics
  3. Products

Products

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: groups related products to allow customers to switch between them, even though each product appears separately in the catalog. For example, a master for a t-shirt includes products in different colors.
  • Products: an item for sale like a red t-shirt, including all its variants. This is what customers see in the catalog. Products are collections of variants belonging together, each sharing underlying similarities (e.g., color of the t-shirt).
  • Variants: A variant is the most specific entity of a product and is what customers add to their cart. Variants are defined by specific attributes, such as size in the case of t-shirts. These items carry stock and price information and are sold in the shops (e.g., sneaker of a 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.

Be aware that Product is the Entity Level that is responded on Product Listing pages such as Category Page, Search Result Page and Product Detail Page.

Variant is the Entity Level that you use to put a specific Product Variant in a Basket or use it for a Transaction.

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

Both types can be translated. This is relevant if you’re working with multiple shop countries and languages.

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.

Shared attributes' translations are fully replaced with those provided in the payload.

In entity related update methods translations of locked attributes are ignored. To update such translations, the query parameter ignoreAttributeLocks=true is necessary.

It is not possible to share attributes of the advanced and advancedList types.

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:

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:

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.

Question/situationAnswer
What information about a product should be shown in the shop front end?All product-related information should be listed in an attribute group in SCAYLE.
Do you have products in the same style but differing in dimensions like color, pattern, or print?If yes, you should assign all the products of the same style to the same master.
Is there information that always remains the same about a product, besides color or size?This information should be defined in an attribute group on the master level.
Is there information that differs between color options?If yes, this information should only be related to the specific color and defined in an attribute group on the product level.
Is there specific information for a product size that is relevant for the customer?If yes, this information should be defined in an attribute group on the variant level.
Is there any product-related information that is requested for third-party tools or reporting that has to be handled in SCAYLE?You should also include this information within SCAYLE attribute groups.
How do you structure your products in your purchase tool?You can usually use your purchase structure to create the same master categories.
Do you plan on selling different product types?For example, furniture and fashion products should be handled with different master categories.
Should you list product information in an advanced or simple attribute group?To decide which type of attribute group to use, consider if the information is reusable. Only free text descriptions or product-specific information (like EANs) should be advanced attribute groups. All product information can usually be listed in simple attribute groups. Please try to mostly use simple attribute groups to reduce database complexity.

APIs

There are different methods to interact with products in the Admin API and Storefront API.

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

Product structure

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

Previous
Custom Data
Next up
Entities