Shop Countries

General

Shop countries can be used to define market-specific assortments, set up supported languages, and configure warehouses.

Assortment

SCAYLE allows users to customize assortments for different countries based on:

assortment related rules
master categories and filters
shop-specific product information

You can assign varying assortments and product scopes for each shop country and define new assortments on a highly granular level by using inclusion and exclusion rules. All rules can be applied to:

attributes
products

To support a shop country with different languages, we need to create multiple entries for the same country code, each representing a different language. Please refer to the example bellow.

Admin API

Create shop country

When you create a shop country, you can concurrently provide additional information along with it. You can add as many of these so-called "properties" to a shop country.

This method is used to create a new shop country. The assortment can be configured afterwards by using the Update Assortment Method.

Price group is set only on shop level, all countries of a shop inherit the price group from the shop itself.

let response = await adminApi.apis.Shops.createShopCountry({shopKey: shopKey}, {requestBody: shopCountry});
let createdShopCountry = response.body;

If there exists a custom data configuration for the shopCountry entity and the custom data isn't provided within the create request, the defaultValue specified in the custom data configuration for each property would be considered.

Parameter	Details
id	Integer READ-ONLY The ID of the shop country created by SCAYLE.
shopKey	String READ-ONLY The key of the shop created by SCAYLE.
countryCode	String ISO 3166 alpha 2 country code.
defaultLanguageCode	String ISO-3166 country code and ISO-639 language code.
supportedLanguageCodes	String List of supported language codes.
url	String Url of the shop country.
active	Boolean READ-ONLY Defines if the shop country is active.
deleted	Boolean READ-ONLY Defines if the shop country is deleted.
priceGroupKey	String READ-ONLY Key of the price group the shop country is assigned to.
currencyCode	String The currency used in the shop country.
assortment	Assortment READ-ONLY Rules that defines what products can be sold within which Shop country
warehouses	ShopCountryWarehouse READ-ONLY A list of warehouses attached to the shop country.
priceRoundings	ShopCountryPriceRounding READ-ONLY List of price rounding configurations.
customData	CustomData Arbitrary fields assigned to Shop countries

Example

let newShopCountry = {
    countryCode: "DE",
    currencyCode: "EUR",
    defaultLanguageCode: "de_DE",
    supportedLanguageCodes: ["de_DE", "en_GB"],
    url: "https://ms.de"
};

let response = await adminApi.apis.Shops.createShopCountry({shopKey: "ms"}, {requestBody: newShopCountry});
let createdShopCountry = response.body;

Create a shop country with different languages

To create a shop country for Switzerland with three different languages—German, French, and Italian—you would set up three separate entries, each with the country code for Switzerland but differentiated by the language attribute.

Prerequisites:

existing shop identified by ms shopKey
existing countries identified by DE, FR, IT
existing languages identified by locale de_DE, fr_FR, it_IT
existing currency identified by EUR

Each country code and locale combination must be unique. \

For instance, if you want to create entries for Switzerland with different languages, you must ensure that each entry has a distinct locale, such as:

Country Code: CH, Locale: de-CH (German)
Country Code: CH, Locale: fr-CH (French)
Country Code: CH, Locale: it-CH (Italian)

Each of these combinations represents a unique country and language setting. Duplicate combinations of country code and locale are not allowed because they need to uniquely identify a specific configuration for the shop.

In case of duplicate, the endpoint would respond with:

errorKey: DEFAULT_LANGUAGE_NOT_UNIQUE
message: Country with the given language already exists in the shop

// create shop country with German language
let germanShopCountry = {
    countryCode: "DE",
    currencyCode: "EUR",
    defaultLanguageCode: "de_DE",
    url: "https://ms.de"
};

let response = await adminApi.apis.Shops.createShopCountry({shopKey: "ms"}, {requestBody: germanShopCountry});
let createdGermanShopCountry = response.body;

// create shop country with French language
let frenchShopCountry = {
    countryCode: "FR",
    currencyCode: "EUR",
    defaultLanguageCode: "fr_FR",
    url: "https://ms.fr"
};

let response = await adminApi.apis.Shops.createShopCountry({shopKey: "ms"}, {requestBody: frenchShopCountry});
let createdFrenchShopCountry = response.body;

// create shop country with Italian language
let italianShopCountry = {
    countryCode: "IT",
    currencyCode: "EUR",
    defaultLanguageCode: "it_IT",
    url: "https://ms.it"
};

let response = await adminApi.apis.Shops.createShopCountry({shopKey: "ms"}, {requestBody: italianShopCountry});
let createdItalianShopCountry = response.body;

In such a case, when having multiple shop countries with the same country code, to avoid errors, we recommend using the shop country ID, instead of shop country code, when performing GET / POST / PUT / DELETE requests that are bound to shop country (endpoint URLs having the /shops/{shopKey}/countries/{countryCode} namespace).

If you tried to get a shop country by country code, the GET /shops/{shopKey}/countries/{countryCode} would respond with:

errorKey: SHOP_COUNTRY_IS_AMBIGUOUS
message: Shop country can not be identified due to duplicates

To overcome this issue, you would need to send the shop country ID as countryCode.

Update a shop country

In SCAYLE, you can update shop countries at any time. The provided information will replace current values and might delete old ones, if specific conditions do not apply.

This method is used to update an existing shop country.

Updating a shop country can have impact on your product assortment. This process can take some time and takes place in the background. Also as shop country price group is inherited from the shop it can not be updated.

In general this method replaces the country with the provided information, meaning not provided properties will get deleted.

let response = await adminApi.apis.Shops.updateShopCountry({shopKey: shopKey, countryCode: countryCode}, {requestBody: shopCountry});
let updatedShopCountry = response.body;

Properties

Parameter	Type	Description	Required	Read Only
id	integer	The ID of the shop country created by SCAYLE.	true	true
shopKey	string	The key of the shop created by SCAYLE.	true	true
countryCode	string	ISO 3166 alpha 2 country code.	true	false
defaultLanguageCode	string	ISO-3166 country code and ISO-639 language code.	true	false
supportedLanguageCodes	string	List of supported language codes.	false	false
url	string	URL of the shop country.	true	false
active	boolean	Defines if the shop country is active.	false	true
deleted	boolean	Defines if the shop country is deleted.	false	true
priceGroupKey	string	Key of the price group the shop country is assigned to.	false	true
currencyCode	string	The currency used in the shop country.	false	false
assortment	Assortment	Rules that define what products can be sold within which shop country.	false	true
warehouses	ShopCountryWarehouse	A list of warehouses attached to the shop country.	false	true
priceRoundings	ShopCountryPriceRounding	List of price rounding configurations.	false	true
customData	CustomData	Arbitrary fields assigned to shop countries.	false	false

Examples

let response = await adminApi.apis.Shops.getShopCountry({shopKey: "ms", countryCode: "DE"}); 
let shopCountry = response.body;

shopCountry.url = "https://ms.de";

let updateResponse = await adminApi.apis.Shops.updateShopCountry({shopKey: "ms", countryCode: "DE"}, {requestBody: shopCountry});
let updatedShopCountry = updateResponse.body;

Get shop country

This method can be used to get an existing shop country by providing the shop key and the country code.

This method allows to include nested resources using the with parameter.

let response = await adminApi.apis.Shops.getShopCountry({shopKey: shopKey, countryCode: countryCode});
let shopCountry = response.body;

Options

Parameter	Details
with	String Allows to load the following nested resources within this request: assortment warehouses priceRoundings customData

Examples

Get a Shop Country

let response = await adminApi.apis.Shops.getShopCountry({shopKey: "ms", countryCode: "DE"});
let shopCountry = response.body;

console.log(shopCountry.url);

Get a Shop Country with Assortment

let response = await adminApi.apis.Shops.getShopCountry({shopKey: "ms", countryCode: "DE", with: "assortment"});
let shopCountry = response.body;

shopCountry.assortment.attributes.forEach(
    attribute => console.log(attribute.name)
);

Get a collection of shop countries

SCAYLE allows you to request multiple shop countries at the same time, considering different parameters to narrow down the query, e.g. language.

This method can be used to get a collection of existing shop countries. It is possible to refine the search by applying filters in the options.

This method allows to include nested resources using the with parameter.

let response = await adminApi.apis.Shops.getShopCountries({shopKey: shopKey});
let shopCountries = response.body.entities;

Examples

let response = await adminApi.apis.Shops.getShopCountries({shopKey: "ms"});
let shopCountries = response.body.entities;

shopCountries.forEach(
    shopCountry => console.log(shopCountry.countryCode)
);

Manage Shop Countries Custom Data

Custom data gives you the flexibility to assign data fields to entities while keeping the overall data structure consistent. For example, it is possible to use custom data to add SEO information or to display content elements such as special banners.

Custom data schemas are configurable via Custom Data Configuration.

For more information, see the Admin API Reference for Shop Countries Custom Data.