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.

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.

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.

JavaScriptPHPcURLJava

Copy

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.

Examples

JavaScriptPHPcURLJava

Copy

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.

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

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

Examples

Create a merchant-specific price valid from now

JavaScriptPHPcURLJava

Copy

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

JavaScriptPHPcURLJava

Copy

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

JavaScriptPHPcURLJava

Copy

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

JavaScriptPHPcURLJava

Copy

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

JavaScriptPHPcURLJava

Copy

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;