Interact with Admin API in Multi Merchant Setup

General

In SCAYLE, a merchant represents a seller of goods to the end customer. Merchants affect on the product assortment, prices and stocks.

When creating a new merchant you can specify its name, a reference key and an optional priority parameter. After creating a merchant, you can additionally configure contact information and return addresses.

Default Merchant

The default merchant is a merchant that was created first, i.e. has the lowest ID.

Priority

When several merchants sell the same product variant, the price of the merchant with the highest priority will be displayed in the shop, but only if it's available at least in one warehouse attached to the merchant. If it is not available, the product variant will be sold at the price of the second-highest priority merchant and so on. The default priority for all merchants is 0.

Carriers

A carrier is a service that delivers goods to customers. After creating carriers in the system, you can associate multiple carriers with a merchant on a country basis. For example, it is possible to configure that a merchant delivers products using Hermes in Germany, but DHL in Italy.

Warehouses

Warehouses are used to store sellable items. When we say that an item is in stock and available, we mean that it has non-zero quantity in a warehouse. A single merchant might use multiple warehouses. In addition, different merchants might use the same warehouses.

The process of configuring warehouses for a merchant depends on the number of merchants in the system. If there are multiple merchants in the system, you have to start with creating a warehouse. Then you can attach it to a shop country and attach it to a merchant of your choice.

Single-Merchant Environment

If the SCAYLE platform has only one merchant, you can use this method. It will automatically create a warehouse with the given reference key if it doesn't exist, and then attach it to the specified shop country and the default merchant.

Multi-Merchant Environment

If there are multiple merchants in the system, you have to start with creating a warehouse. Then you can attach it to a shop country and attach it to a merchant of your choice.

Product Assortment

Product assortment refers to a catalogue of products and its variations. You can limit the assortment to specific merchants or exclude some merchants from the shop.

Prices

Prices represent the amount of money required to purchase a product variant. SCAYLE allows you to define prices for each merchant in the system by providing a merchantReferenceKey in the payload.

If merchantReferenceKey is not provided, SCAYLE assumes that the given price information belongs to the default merchant.

Stocks

Stocks represent the number of available product variants in a warehouse. Similarly to prices, you can create merchant-specific stocks. The merchant context is controlled by the merchantReferenceKey field.

A warehouse with the given reference key must exist in the system. In addition, it must be connected to the merchant identified by merchantReferenceKey. If merchantReferenceKey is omitted, SCAYLE assumes that the given stock information belongs to the default merchant.

Admin API

Update assortment

In SCAYLE, you update shop country assortments by narrowing down or extending product sets based on different criteria. By including or excluding master categories, product IDs, or attributes, you replace the current assortment with the updated one.

This method is used to update a shop country assortment.

This method does not support partial updates.
This process can take some time and is processed in the background.

Parameter	Details
masterCategories	MasterCategoryAssortmentConfiguration Configuration of master category includes/excludes.
products	ProductAssortmentConfiguration Configuration of product includes/excludes.
attributes	AttributeAssortmentConfiguration Configuration of attribute includes/excludes.
merchantReferenceKeys	MerchantAssortmentConfiguration Configuration of merchant includes/excludes.

let assortment = {
    masterCategories: {
        include: [
            [
                "Fashion",
                "Shirts"
            ],
            [
                "Fashion",
                "Shoes"
            ],
        ]
    },
    products: {
        exclude: [1,2]
    },
    attributes: [
        {
            name: "color",
            exclude: ["red", "yellow"]
        }
    ],
    merchantReferenceKeys: {
        include: ["acme"]
    }
};

let response = await adminApi.apis.Shops.updateAssortment({shopKey: "ms", countryCode: "DE"}, {requestBody: assortment});
let updatedAssortment = response.body;

Create stock information

You can update stock information by overriding existing information with a more recent change on warehouse stocks.

If you provide a changedAt date which is older than the last processed stock information, the stock will not change as this will be considered as outdated information. In this case the method will return the current stock. If you would like to find out if the information you sent was outdated, you have to compare what you’ve sent to what was returned in the response.
Sending a stock update without sellableWithoutStock flag will reset the value to false (the default value).
It is not possible to update stock information for composite product variants.
merchantReferenceKey can be provided to create merchant-specific stocks. Note that merchantReferenceKey must refer to one of the merchants provided on product creation.

Make sure the provided warehouseReferenceKey exists before you start creating a stock. You can create a new shop warehouse.

Be aware that the referenced warehouse must be linked to a shop country.
Otherwise, the shop country cannot use the stock.

Parameter	Details
quantity	Integer Current quantity of SKU.
warehouseReferenceKey	String Reference key of warehouse for which the stock update is related to.
changedAt	String Date time when the stock changed in Iso8601 format.
sellableWithoutStock	Boolean Defines if the variant can be sold even when the available stock is 0.
merchantReferenceKey	String A merchant reference key the stock belongs to.

Examples

let newStock = {
    quantity: 10,
    warehouseReferenceKey: "myWarehouse",
    changedAt: "2020-07-23T11:30:58+00:00",
    merchantReferenceKey: "merchant-1"
};

let response = await adminApi.apis.Stocks.createProductVariantStock(
    {variantIdentifier: 1},
    {requestBody: newStock}
);

let createdStock = response.body;

Create/update a price

Prices are defined on a product variant level and contain all information about prices, taxes and validity — upcoming prices can also be defined for automatic future price updates.

This method can be used to create a new Product Variant Price. You can create prices which are valid from now or in the future. If there is an already existing price for the same validation time frame, it will get replaced.

If multiple prices of the same variant are to be created then use update-variant endpoint which supports sending multiple prices at once.

Creating a new price, which is valid from the time of creation, will invalidate the current active price and become the new active one based on the dimensions explained on the prices overview page.

It is not possible to create a price for a composite product variant, when the automatic price calculation for composite variants is enabled.

merchantReferenceKey can be provided to create a merchant-specific price.

Note that merchantReferenceKey must refer to one of the merchants provided on product creation.

Parameter	Details
key	String READ-ONLY Key assigned by SCAYLE.
price	Integer Price of the variant.
oldPrice	Integer Old price of the variant.
recommendedRetailPrice	Integer Recommended retail price of the variant.
buyingPrice	Integer Buying price of the variant.
tax	Double A valid tax rate.
countryCode	String ISO 3166 alpha 2 country code.
currencyCode	String ISO 4217 currency code.
groupKey	String Key of the group the price is assigned to.
promotionKey	String Key of the promotion the price is assigned to.
unitPrice	ProductVariantUnitPrice Describes the price for a specific unit.
validFrom	String Controls when the price will be activated. If not present or null, the valid from is specified from now.
validTo	String Controls when the price will be deactivated. If not present or null, the price is valid forever.
merchantReferenceKey	String A merchant reference key the price belongs to.

Examples

Create a merchant-specific price valid from now

let newPrice = {
    price: 2499,
    tax: 19.0,
    currencyCode: "EUR",
    countryCode: "DE",
    merchantReferenceKey: "merchant-1"
};

let response = await adminApi.apis.Prices.createProductVariantPrice(
    {variantIdentifier: 1},
    {requestBody: newPrice}
);

let createdPrice = response.body;

Create Valid Price for Future

let newPrice = {
    price: 2499,
    tax: 19.0,
    currencyCode: "EUR",
    countryCode: "DE",
    validFrom: "2022-07-23T11:30:58+00:00"
};

let response = await adminApi.apis.Prices.createProductVariantPrice(
    {variantIdentifier: 1},
    {requestBody: newPrice}
);

let createdPrice = response.body;

Create Valid Expiring Price

let newPrice = {
    price: 2499,
    tax: 19.0,
    currencyCode: "EUR",
    countryCode: "DE",
    validTo: "2021-01-01T08:00:00+00:00"
};

let response = await adminApi.apis.Prices.createProductVariantPrice(
    {variantIdentifier: 1},
    {requestBody: newPrice}
);

let createdPrice = response.body;

Create Price with Unit Price

let newPrice = {
    price: 2499,
    tax: 19.0,
    currencyCode: "EUR",
    countryCode: "DE",
    unitPrice: {
        unit: "ml",
        amount: 100,
        price: 249
    }
};

let response = await adminApi.apis.Prices.createProductVariantPrice(
    {variantIdentifier: 1},
    {requestBody: newPrice}
);

let createdPrice = response.body;

Create Merchant-Specific Price

let newPrice = {
    price: 2499,
    tax: 19.0,
    currencyCode: "EUR",
    countryCode: "DE",
    merchantReferenceKey: "merchant-1"
};

let response = await adminApi.apis.Prices.createProductVariantPrice(
    {variantIdentifier: 1},
    {requestBody: newPrice}
);

let createdPrice = response.body;