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

When Storefront API returns a price, it always uses a structured price object, such as:

json

Copy

Price Object Fields

This price object structure is reused across products, variants and basket pricing; only the context (per variant, per product, per basket item) differs.

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.
• campaignKey=BLACKWEEK triggers a campaign reduction.
• No pricePromotionKey is passed, so the campaign applies directly to the base/country price.
• The campaign discount appears in appliedReductions .
• lowestPriorPrice is returned because the campaign price is lower than a previously valid 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 triggers the campaign reduction (if configured for this product/variants).
• No pricePromotionKey is passed; the campaign applies directly to the base/country price.
• Campaign discounts appear in appliedReductions.
• priceRange summarizes the product’s sellable variants for this request.

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 triggers the campaign reduction (if configured for this variant).
• No pricePromotionKey is passed; the campaign applies directly to the base/country price.
• The variant response contains its final price object for this single variant.

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 on top (shows in appliedReductions).
• Basket pricing is recalculated on every GET.
• items[].price.unit = final unit price; items[].price.total = unit × 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:

• pricePromotionKey=VIP-PPK-2025 sets the effective starting price (no reduction entry).
• campaignKey=BLACKWEEK applies a relative discount on top of PPK, 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:

• pricePromotionKey changes the effective price but does not mark a product as “on sale” and does not add an entry to appliedReductions.
• 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

A product will be returned as part of a sale category, if the following conditions are met:

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.