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

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

JavascriptPHPcURLJava

Copy

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.

Create Valid Price from Now

JavascriptPHPcURLJava

Copy

Create Valid Price for Future

JavascriptPHPcURLJava

Copy

Create Valid Expiring Price

JavascriptPHPcURLJava

Copy

Create Price with Unit Price

JavascriptPHPcURLJava

Copy

Create Merchant-Specific Price

JavascriptPHPcURLJava

Copy

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.

Method Signature

JavascriptPHPcURLJava

Copy

Parameters

List of Prices

JavascriptPHPcURLJava

Copy

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

JavascriptPHPcURLJava

Copy

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.
• It is not allowed to delete a custom price. When trying to remove a custom price, endpoint would respond with 400 Bad Request, PRODUCT_VARIANT_CUSTOM_PRICE_CANNOT_BE_DELETED error key.

Delete a Price

JavascriptPHPcURLJava

Copy

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

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

Only the following prices are affected:

• prices
• old prices
• promotion prices
• campaign prices

Create a Shop Country Price Rounding

Method Signature

JavascriptPHPcURLJava

Copy

Example

JavascriptPHPcURLJava

Copy

Delete a Shop Country Price Rounding

Method Signature

JavascriptPHPcURLJava

Copy

Example

JavascriptPHPcURLJava

Copy

Get a Shop Country Price Rounding Collection

Method Signature

JavascriptPHPcURLJava

Copy

Example

JavaScriptPHPcURLJava

Copy

Rounding Basket/Order prices

In case rounding also needs to be applied on the total of an basket/order, a different configuration shall be applied on shop level.

Order value precision

• 1,0
• 5,0

Rounding Type

• nearest
• up
• down

Rounding basket/order prices when promotions are applied

Whenever promotions or coupons are applied on the Basket, the configured rounding will be taken into consideration when calculating the final item price.

Example:

Rounding order total

In case a configuration is also set on order level for rounding, the total value of the order will be rounded as per configuration. This will also ensure that, whenever vouchers or other costs are applied during Checkout, the total value or the order will follow the rule set on configuration level.

Storefront API

This section explains how the Storefront API resolves and returns prices at the time of the request.

How Prices Are Returned

The Storefront API returns prices as structured objects. The exact fields depend on where the price appears. The sections below describe each surface.

Product and Variant Prices

Products and variants return the full price object. It appears at variants[].price (List Products, Get a Product), at price (Get a Variant), and as priceRange.min and priceRange.max.

The lowest prior price is returned separately, as a sibling of the price object (variants[].lowestPriorPrice), requested with variants.lowestPriorPrice.

json

Copy

Basket Prices

Basket prices use a reduced price object. It appears at cost and at each item's price.unit and price.total. It returns appliedReductions and the standard fields, but not beforeSaleWithTax, totalAppliedReductions, or reductionsRelativeTo.

Each basket item returns lowestPriorPrice as a sibling of its price. The item also embeds the variant at variant.price, which carries the full product/variant price object, including beforeSaleWithTax, totalAppliedReductions, and reductionsRelativeTo. Read those from variant.price when a basket line needs them.

json

Copy

Order Prices

Order prices use their own price objects. They return the standard price fields and appliedReductions, but not beforeSaleWithTax, totalAppliedReductions, or reductionsRelativeTo.

Wishlist Prices

Wishlist items do not carry their own price object. Prices come from the embedded product or variant, requested with items.variant or items.product. That embedded price is the full product/variant price object, including beforeSaleWithTax, totalAppliedReductions, and reductionsRelativeTo. Read pricing from items.variant.price (or items.product.variants[].price).

Sale Prices and Lowest Prior Price Enforcement

A reduction is always measured against a reference price, called the reduction anchor. The field reductionsRelativeTo tells you which price that is:

• beforeSaleWithTax: the old price - the regular price before the current sale.
• lowestPriorPrice.withTax: the lowest price of the last 30 days.

You can turn on Lowest Prior Price enforcement to comply with EU price-transparency rules. It is configured separately for sale prices and campaign prices in the SCAYLE Panel under Sale Indicator Rules. Enforcement decides which anchor is used, and whether a reduction is advertised at all. Always read reductionsRelativeTo and strike the price names. Do not assume the previous price is always the reference.

The four cases below all describe the same variant: a current price (withTax) of 5790 and a previous price (beforeSaleWithTax) of 11900. Only the shop country's enforcement setting and the 30-day low change. The excerpts show just the price fields that matter, plus the sibling lowestPriorPrice.

1. Enforcement off (default): measured against the previous price

The reduction is 51% off the previous price 11900. reductionsRelativeTo is beforeSaleWithTax. A lowest prior price may still be returned, but it is not used.

json

Copy

2. Enforcement on, current price below the 30-day low: genuine sale

The 30-day low is 8000. Because the current price 5790 is below it, the sale is genuine and the reduction is measured against the low: 28% off 8000, not off the previous price. reductionsRelativeTo is lowestPriorPrice.withTax. beforeSaleWithTax is still returned.

json

Copy

3. Enforcement on, current price not below the 30-day low: no sale

The 30-day low is 5600. The current price 5790 is not below it, so there is nothing to advertise. appliedReductions is empty, totalAppliedReductions and reductionsRelativeTo are null, and the product is not treated as on sale, even though 5790 is still below the previous price 11900. This is the EU Omnibus case.

json

Copy

4. Enforcement on, but no lowest prior price: fallback to the previous price

Without a 30-day low, for example on a product without enough recent price history, enforcement has no reference to apply. The reduction falls back to the previous price, exactly as when enforcement is off, and reductionsRelativeTo is beforeSaleWithTax.

json

Copy

Campaign context

Enforcement is configured independently for the base sale price and the campaign price, so a variant can be a genuine sale on one and suppressed on the other. When your request includes a campaignKey, the same four cases apply to the campaign price, totalAppliedReductions reflects the combined reduction (for example a base sale plus the campaign), and appliedReductions lists each reduction separately.

For example, a variant with a previous price of 10000 that is 20% off as a base sale and then part of a 25% campaign returns both reductions in appliedReductions, while totalAppliedReductions gives the combined 40% off the previous price:

json

Copy

The sale takes 20% off the 10000 previous price (2000), the campaign takes a further 25% off the resulting 8000 (2000), and totalAppliedReductions reports the combined 4000 (40%) measured against beforeSaleWithTax.

General Pricing Behavior

Price Calculation

When Storefront API calculates a price, it evaluates the pricing layers in the following order:

• If a pricing layer does not exist, the Storefront API falls back to the next one.

Where Prices Appear in Storefront API

Products → List Products

• Endpoint: GET /v1/products

Returned Price Fields

Request example:

JavaScriptcURL

Copy

Context of the request:

• shopId=10001 applies country-specific price, currency (EUR), and VAT rules.
• with=priceRange,variants.lowestPriorPrice returns the variants with their prices, the product price range, and the lowest prior price for each variant.
• The sale reduction appears in appliedReductions, and the combined figure in totalAppliedReductions.
• lowestPriorPrice is returned as a sibling of each variant's price.

Response (excerpt):

json

Copy

Products → Get a Product

• Endpoint: GET /v1/products/{productId}

Request example:

JavaScriptcURL

Copy

Context of the request:

• shopId=10001 applies country-specific price, currency (EUR), and VAT rules.
• campaignKey=BLACKWEEK applies the campaign reduction on top of the base/country price.
• This product is on sale and also part of the campaign, so appliedReductions lists both entries and totalAppliedReductions is the combined figure.
• lowestPriorPrice is returned as a sibling of each variant's price.

Response (excerpt):

json

Copy

Filters (Price Object)

• Endpoint: GET /v1/filters (You may also receive filters embedded in other endpoints.)

Difference of the price facet as opposed to per-product ranges:

Request example:

JavaScriptcURL

Copy

Context of the request:

• categoryId=123 limits filters to products in this category.
• shopId=10001 applies country-specific price, currency (EUR), and VAT rules.
• with=values returns filter values, including the price facet with min / max.
• campaignKey=BLACKWEEK applies campaign reductions where available, affecting the returned price boundaries.
• Each product contributes one value: the price of its cheapest sellable variant in this request context.

Response (excerpt):

json

Copy

Variants → Get a Variant

• Endpoint: GET /v1/variants/{variantId}

Request example:

JavaScriptcURL

Copy

Context of the request:

• shopId=10001 applies country-specific price, currency (EUR), and VAT rules.
• campaignKey=BLACKWEEK applies the campaign reduction on top of the base/country price.
• This variant is on sale and also part of the campaign, so appliedReductions lists both entries and totalAppliedReductions is the combined figure.
• lowestPriorPrice is returned as a sibling of the price object when requested with lowestPriorPrice.

Response (excerpt):

json

Copy

Basket → Get a Basket

• Endpoint: GET /v1/baskets/{basketId}

Request example:

JavaScriptcURL

Copy

Context of the request:

• shopId=10001 applies country-specific price, currency (EUR), and VAT rules.
• campaignKey=BLACKWEEK applies a campaign reduction, shown in appliedReductions.
• Basket pricing is recalculated on every GET.
• items[].price.unit is the final unit price and items[].price.total is unit times quantity.
• cost returns the basket totals.

Response (excerpt):

json

Copy

Basket → Add or Update

• Endpoints:
  • POST /v1/baskets/{basketId}/items
  • PUT /v1/baskets/{basketId}/promotions

Request example:

JavaScriptcURL

Copy

Context of the request:

• campaignKey=BLACKWEEK applies a campaign reduction, shown in appliedReductions.
• The returned basket contains fully recalculated prices for all items and totals.

Response (excerpt):

json

Copy

campaignKey vs. pricePromotionKey

Assume a variant has the following pricing configuration:

• Base price: €219.00
• Promotion price (PPK): €199.00
• Active campaign discount: 10%

This shows that:

• campaignKey applies a reduction on top of the resolved price (base, country, merchant, customer group, or PPK) and does appear in appliedReductions (usually with category: "campaign" and the campaignKey as a label).

Price Range And Filter Calculation

To fully understand how priceRange and the filters price facet behave, it’s important to clarify which variants are included, how prices are resolved, and how aggregation differs between product-level ranges and global filters:

• Sellable variants only: Variants without a valid resolved price (for example, missing base price) are ignored in both priceRange and filters.
• Context-aware: Campaigns (campaignKey), price promotions (pricePromotionKey), customer group, merchant, and other filters (e.g., size, color) all influence which variants are considered sellable and what their final prices are.
• Different aggregation levels:
  • priceRange aggregates within a single product.
  • The price facet aggregates across products in the current result set.

Both use the fallback logic of general pricing behavior.

Sale And NoSale Category Behavior

You have the option only to include products that are on sale in a category as described here (this does not include products included in campaigns or other promotions). The opposite, where you only include products that are not on sale, is also possible. Whether a category is a sale or a non-sale category can be identified through the reserved sale property in the Storefront API. They will be called sale and noSale categories from here on.

Request example:

JavaScriptcURL

Copy

Response (sale category):

json

Copy

International Prices

Prices may differ from shop to shop. That may be due to local prices being applied, as well as the different VATs or currencies being applied to different shops.

Edge Cases

These edge cases are important for interpreting price ranges, filters, and basket values.