Manage Prices

General

Prices in SCAYLE can be concurrently applied to different countries, groups and campaigns as needed.

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. For a specific variant, there can be multiple prices active at the same time based on the following dimensions:

countryCode: The country in which the price is effective.
groupKey: Price groups can be used to apply different prices in different shops within the same country (e.g., B2C vs. B2B).
promotionKey: The price promotion key can be used to have multiple valid prices for the same country and price group within the same shop at the same time. The Storefront API can be used to retrieve a specific price by sending a request with a defined price promotion key.

The currency (currencyCode) is not part of these dimensions as it must match the respective country.

Price key

Every new price gets a generated key. This key might change due to certain conditions. For example, when a future price becomes an active price, the key is modified.

Merchant-Specific Prices

You can create prices for a specific merchant by providing its reference key in the merchantReferenceKey field.

Product Variant Price Entity

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.

Admin API

Create/Update a Price

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

About this Method

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.

Method Signature

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

let createdPrice = response.body;

Details

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.
Future prices are activated by a price activator cron job running every hour. Old prices are then deactivated.
merchantReferenceKey can be provided to create a merchant-specific price. Note that merchantReferenceKey must refer to one of the merchants provided on product creation.

If you send prices by specifying a merchantReferenceKey for which no product variant exists, you will receive the error message MERCHANT_REFERENCE_KEY_OUT_OF_RANGE.

Create Valid Price from Now

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

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;

Get a Collection of Prices

When you request variant prices, you can extend the query with several identifiers to get multiple active prices.

About this Method

This method can be used to get a collection of existing product variant prices.

The price collection contains currently active and future prices. Expired or invalid prices are not included.

Method Signature

let response = await adminApi.apis.Prices.getProductVariantPrices({variantIdentifier: variantIdentifier});
let prices = response.body.entities;

Parameters

Parameter	Details
entities	ProductVariantPrice A collection of product variant prices.

Parameter

Details

entities

ProductVariantPrice

A collection of product variant prices.

List of Prices

let response = await adminApi.apis.Prices.getProductVariantPrices({variantIdentifier: 1});
let prices = response.body.entities;

prices.forEach(
    price => console.log(price.price)
);

Delete a product variant price

You can easily delete prices by using the respective identifiers.

About this Method

This method can be used to delete a price.

Method Signature

await adminApi.apis.Prices.deleteProductVariantPrice({variantIdentifier: variantIdentifier, priceKey: priceKey});

Details

It is not possible to remove a price from a composite product variant, when the automatic price calculation for composite variants is enabled.
It is not allowed to delete a merchant price other than a future price.

Delete a Price

await adminApi.apis.Prices.deleteProductVariantPrice({variantIdentifier: 1, priceId: '1-10'});

Price Rounding

A shop country price rounding represents a price rounding assigned to a shop country.

SCAYLE allows users to create and manage any number of price rounding configurations.

The primary purpose of this feature is to allow users to customize price rounding settings.

Price rounding precision

You can set the price rounding precision (the value by which the price is rounded up/down/ to the nearest integer). For simplicity, the precision values used in the following table are allowed:

1.0
5.0
0.05
0.95
0.99

Example of precision value rounding

Precision	Rounding Type	Price	Rounded Price
1.0	nearest	1458.90	1459
1.0	up	1458.90	1459
1.0	down	1458.90	1458
5.0	nearest	1458.90	1460
5.0	up	1458.90	1460
5.0	down	1458.90	1455
0.05	nearest	1.02	1
0.05	down	1.02	1
0.05	up	1.02	1.05
0.99	nearest	14.87	14.99
0.99	down	14.87	13.99
0.99	up	14.87	14.99
0.9	nearest	14.87	14.9
0.9	down	14.87	13.9
0.9	up	14.87	14.9

The price rounding configurations apply at the shop country and currency level. For example, a configuration set for AY CH will specifically impact prices in Swiss Francs (CHF) for the corresponding shop and country.

By default, price rounding is disabled. To have it enabled, at least one price rounding configuration should be created.

Only the following prices are affected:

prices
old prices
promotion prices
campaign prices

Create a Shop Country Price Rounding

Method Signature

const response = await adminApi.apis.PriceRoundings.createShopCountryPriceRounding(
    { shopKey: shopKey, countryCode: countryCode },
    { requestBody: shopCountryPriceRounding }
);
const createdShopCountryPriceRounding = response.body;

Example

let newShopCountryPriceRounding = {
    currencyCode: "EUR",
    precision: "1.00",
    roundingType: "nearest",
};

const response = await adminApi.apis.PriceRoundings.createShopCountryPriceRounding(
    {
        shopKey: "ms",
        countryCode: "DE"
    },
    {
        requestBody: newShopCountryPriceRounding
    }
);

const createdShopCountryPriceRounding = response.body;

Delete a Shop Country Price Rounding

Method Signature

await adminApi.apis.PriceRoundings.deleteShopCountryPriceRounding(
    { shopKey: shopKey, countryCode: countryCode, priceRoundingId: priceRoundingId }
);

Example

adminApi.apis.PriceRoundings.deleteShopCountryPriceRounding(
    {
        shopKey: "ms",
        countryCode: "DE",
        priceRoundingId: 123
    }
);

Get a Shop Country Price Rounding Collection

Method Signature

const response = await adminApi.apis.PriceRoundings.getShopCountryPriceRoundings(
    { shopKey: shopKey, countryCode: countryCode },
);
const priceRoundings = response.body.entities;

Example

const response = await adminApi.apis.PriceRoundings.getShopCountryPriceRoundings("ms", "DE");
const priceRoundings = response.body.entities;

priceRoundings.forEach(
    priceRounding => console.log(priceRounding.id)
);