Import Products

General

Now that you're familiar with the three-level product structure and have defined master categories and attribute groups for Fashion Store, you’re ready to dive deeper into the product creation process within SCAYLE.

First, let's start with an overview of the five steps necessary to create a sellable product within SCAYLE:

Create a product.
Add at least one variant to the product.
Add at least one image to the product.
Add price information to at least one variant.
Add stock information to at least one variant.

We'll explain each topic in a separate section of this guide, and in the end, you’ll have successfully created a sellable product.

Admin API

Create your first product

There are three different ways to create products in SCAYLE:

Via the Admin API.
Manually within the SCAYLE Panel.
Manually by importing a product list file into the SCAYLE Panel.

Create products via the Admin API because this is the easiest way to handle lots of products.

The Admin API allows you to create, update, delete and fetch products. Each endpoint is described in more detail in the products section of the Admin API reference guide. For the sake of this tutorial, we will focus on creating products via the create endpoint.

Breaking down the product creation endpoint

POST /products

The product creation endpoint can technically receive and process a complete product structure, including prices and stock. However, this can slow down the processing time, so we recommend using the dedicated endpoints separately and orchestrating them. We’ll demonstrate this approach in the following chapter.

Furthermore, the endpoint supports a couple of query parameters that can be used to customize the product creation request. For example, you can specify what information you want the Admin API to provide in the request response.

Request body

In the request body, you need to specify all the details about the product you want to create. Find parameters relevant to this tutorial in the table below.

Parameter	Details
id	Integer READ-ONLY The ID of the product created by SCAYLE.
problems	String READ-ONLY If product is in problem state, the reasons are listed here.
referenceKey	String A key that uniquely identifies the product (e.g., a shirt in a specific color) within the tenant's ecosystem.
name	String The localized product name. At least the base language that is configured in SCAYLE is mandatory.
master	Master The master the product is attached to.
state	String The state of the product determined by the state evaluation process. The only possible values to request are `live`, `draft` and `blocked`. The `problem` state can only be the result of the state evaluation process. If product is in problem state, the reasons are listed in read-only 'problems' field. The `new` and `inApproval` states can be set in the SCAYLE Panel.
attributes	Attribute A list of attributes attached to the product.
variants	ProductVariant A list of product variants attached to the product.
images	ProductImage A list of product images attached to the product.
productSortings	ProductSorting A list of product sortings.
customData	CustomData
isComposite	Boolean READ-ONLY Indicates whether the product is composite.

Parameter	Type	Details
`merchantReferenceKeys`	`STRING ARRAY`	If there is more than one merchant in the system, you might want to define merchants that sell the product. This can be done by listing merchant reference keys in the `merchantReferenceKeys` field. Prices and stocks provided along with the product information can be also merchant-specific. The relation to a merchant is established via the `merchantReferenceKey` field, which must be within the range of merchants defined for the product.
`referenceKey`	`STRING`	A key that uniquely identifies the product (e.g., a shirt in a specific color) within the tenant's ecosystem.
`name`	`OBJECT`	The localized product name. At least the base language that is configured in SCAYLE is mandatory. The base language is set when the SCAYLE commerce engine instance is initiated.
`master`	`OBJECT`	The master object includes the fields `referenceKey`, `categories` and `attributes`. If you create a new product for which no master exists in SCAYLE, you create the master simultaneously with the first product in the product creation request. Therefore, you can provide information for all three fields to initially define and create your master. If a master already exists, providing only the master referenceKey is enough to link the new product to the existing master. The product will then inherit all attributes and categories of the existing master.
`state`	`STRING`	The state of the product determined by the state evaluation process. The only possible values to assign are live and draft.
`attributes`	`ARRAY OBJECT`	A list of attributes attached to the product. It is possible to specify a set of attributes, which will be either linked to the product if they already exist or created and subsequently linked to the product. The attribute's `name` must refer to an attribute group of the `product` level. If you want to get more detailed information, please use the Product Attributes Section.
`variants`	`ARRAY OBJECT`	It is possible to specify a set of product variants, which will be either linked to the product if they already exist or created and subsequently linked to the product. If you want to get more detailed information, please use the Variants Section.
`images`	`ARRAY OBJECT`	It is possible to specify a set of product images, either by providing a `source` from which the resource can be downloaded or a CDN URL.

Guiding principles when integrating this endpoint:

You can send the whole product structure via the create product endpoint. However, please consider that sending lots of data along with this request can slow down response times.
We recommend using the dedicated endpoints sequentially to create the entire product structures, e.g. first create the product, then the variants, and so on. This approach is also presented in this guide.
You can increase the performance of the create endpoints by setting the with parameter to empty (?with='') to streamline the response body.

Implementation hints

The attribute groups referenced by the provided attributes must be created in advance. Please check Attribute Groups for more details.
During state evaluation, one of the problems you could encounter is system: mandatory attributes are missing. In this case you should check that the payload provides attributes for all the attributes groups configured as mandatory.

Creating an example product for Fashion Store

Now let's create the first product, a black T-shirt, for our demo shop Fashion Store via the Admin API's product creation endpoint.

We can only create one product per request. Therefore, multiple products require multiple requests.

Example Payload

{
  "referenceKey": "FS-100-black",
  "name": {
    "de_DE": "Schwarzes T-Shirt",
    "de_CH": "Schwarzes T-Shirt",
    "fr_FR": "T-shirt noir"
  },
  "state": "live",
  "master": {
    "referenceKey": "FS-100",
    "categories": {
      "paths": [["Storefront", "T-Shirt"]]
    },
    "attributes": [
      {
        "name": "brand",
        "type": "localizedString",
        "value":  {
          "de_DE": "adidas",
          "de_CH": "adidas",
          "fr_FR": "adidas"
        }
      }
    ]
  },
  "attributes": [
    {
      "name": "color",
      "type": "localizedString",
      "value": 
      {
        "de_DE": "schwarz",
        "de_CH": "schwarz",
        "fr_FR": "noir"
      }
    },
    {
      "name": "description",
      "type": "localizedString",
      "value": 
      {
        "de_DE": "Einfarbiges Basic T-Shirt.",
        "de_CH": "Einfarbiges Basic T-Shirt.",
        "fr_FR": "T-shirt basique uni."
      }     
    }
  ]
}

See here for more information on how attribute groups are represented in the SCAYLE Panel and here for the different attribute group types available in the Admin API.

Example Response

{
  "id": 1,
  "referenceKey": "FS-100-black",
  "state": "live",
  "master": {...},
  "name": {...},
}

Parameter	Description
`id`	The response body of a product creation request provides the SCAYLE internal product id generated for the product.

For other requests (e.g., update product) where a productIdentifier has to be provided, the product id or the referenceKey can both be used.

Congratulations: You have successfully created your first product in SCAYLE!

Create a Basic Product

let newProduct = {
    referenceKey: "myReferenceKey",
    master: {
        referenceKey: "myMasterReferenceKey",
        categories: {
            paths: [
                [
                    "Fashion",
                    "Women",
                    "Shirts"
                ]
            ]
        }
    },
    name: {
        de_DE: "Mein Produkt",
        en_GB: "My Product"
    },
    state: "draft"
};

let response = await adminApi.apis.Products.createProduct({}, {requestBody: newProduct});
let createdProduct = response.body;

Create a Complete Product

let newProduct = {
    referenceKey: "myReferenceKey",
    name: {
        "de_DE": "Mein Produkt",
        "en_GB": "My Product"
    },
    state: "live",
    master: {
        referenceKey: "myMasterReferenceKey",
        categories: {
            paths: [
                [
                    "Fashion",
                    "Women",
                    "Shirts"
                ]
            ]
        }
    },
    attributes: [
        {
            name: "color",
            type: "localizedStringList",
            value: [
                {
                    de_DE: "rot",
                    en_GB: "red"
                },
                {
                    de_DE: "blau",
                    en_GB: "blue"
                }
            ]
        }
    ],
    variants: [
        {
            referenceKey: "myVariantKey",
            attributes: [
                {
                    name: "size",
                    type: "simple",
                    value: "M"
                }
            ],
            prices: [
                {
                    price: 2499,
                    tax: 19,
                    currencyCode: "EUR",
                    countryCode: "DE",
                }
            ]
        }
    ],
    images: [
        {
            source: {
                url: "https://example.com/image.jpg"
            }
        }
    ],
    customData: {
        "additionalDetails": "details"
    },
    merchantReferenceKeys: ["merchant-1", "merchant-2"]
};

let response = await adminApi.apis.Products.createProduct({}, {requestBody: newProduct});
let createdProduct = response.body;

Create Product with Options

let newProduct = {
    referenceKey: "myReferenceKey",
    name: {
        "de_DE": "Mein Produkt",
        "en_GB": "My Product"
    },
    state: "live",
    master: {
        referenceKey: "myMasterReferenceKey",
        categories: {
            paths: [
                [
                    "Fashion",
                    "Women",
                    "Shirts"
                ]
            ]
        }
    },
    attributes: [
        {
            name: "color",
            type: "localizedStringList",
            value: [
                {
                    de_DE: "rot",
                    en_GB: "red"
                },
                {
                    de_DE: "blau",
                    en_GB: "blue"
                }
            ]
        },
        {
            "name": "brand",
            "type": "simple",
            "value": "s.Oliver",
        }
    ],
    variants: [
        {
            referenceKey: "myVariantKey",
            attributes: [
                {
                    name: "size",
                    type: "simple",
                    value: "M"
                }
            ],
            prices: [
                {
                    price: 2499,
                    tax: 19,
                    currencyCode: "EUR",
                    countryCode: "DE",
                }
            ]
        }
    ],
    images: [
        {
            source: {
                url: "https://example.com/image.jpg"
            }
        }
    ]
};

let response =
  await adminApi.apis.Products.createProduct(
  { ignoreMasterIfExist: true, updateIfExists: true, ignoreAttributeLocks: true, ignoreCategoryLocks: true },
  { requestBody: newProduct }
);
let createdProduct = response.body;

Further education - SCAYLE Academy

Course

Import your products into SCAYLE

Import Products

Product Data Management
Tech

Robert Merten

VP Tech

Product Data Management

Import your products into SCAYLE

Intermediate
6 lessons
1h 14m

Play tutorial