Multiple Promotions on Item Level
SCAYLE also supports applying multiple promotions to an item, provided specific conditions are met, allowing for complex and layered discount strategies.
Enabling Multiple Promotions on an Item
For an item to receive the benefit of multiple promotions, both of the following conditions must be met:
1. Promotion Configuration
Each individual promotion must be explicitly configured to be combinable with other promotions.
Please note that once the siblingPromotions = TRUE is selected, an allowlist MUST be created and a blocklist CAN also be added.
| Configuration Field | Description | Default Value | Required for Combination |
|---|---|---|---|
siblingPromotions | Boolean flag indicating whether this promotion can be stacked with others on the same item. | false (NO) | true |
Default Behavior: By default, promotions are exclusive. Once two exclusive promotions can apply to the same item, only the highest-priority applicable promotion will be applied.
2. Endpoint Application
The promotion must be assigned to the Basket in either the Add a Variant call or Update an Item call.
Promotion Priority and Application Rules
When multiple combinable promotions are applied to an item, a pre-defined priority mechanism determines the order of application and calculation.
| Priority Level | Promotion Type | Calculation Rule | Example |
|---|---|---|---|
| 1 (Highest) | Combo Deals | Applied first, setting the item's price to the fixed deal price (e.g., '2 for $X' or 'Item A + Item B for $Y'). All subsequent discounts are calculated on this new fixed price. | Combo Deal: Buy Jeans and Shirt for $20.00. |
| 2 | Percentage Discounts | Applied second, calculated on the current item price (which may be the original price or the fixed price after a Combo Deal). | Percentage Discount: 10% off. |
| 3 (Lowest) | Absolute Discounts / Monetary Reductions | Applied last, subtracting a fixed monetary amount from the current item price. | Absolute Discount: $5.00 off. |
Some important topics to be considered:
- It is possible to apply several Buy X Get Y promotions to a basket. A Buy X Get Y promotion does not need to be assigned to existing basket items. For example, a free gift will be added to the basket with the promotion ID assigned, and other basket items will not be updated.
- In case the same promotion type applies to an item (e.g. 2 promotions with absolute discounts), the priority follows the order of application - the first promotion applied to the item is the first one to have the discount calculated.
Example of Priority Application
Scenario: An item (Original Price: $50.00) qualifies for three combinable promotions:
- Combo Deal: Item fixed at $40.00 (Priority 1)
- Percentage Discount: 10% off (Priority 2)
- Absolute Discount: $5.00 off (Priority 3)
| Step | Action | Calculation | Item Price After Step |
|---|---|---|---|
| 0 | Original Price | N/A | $50.00 |
| 1 | Apply Priority 1 (Combo Deal) | Price is set to $40.00 | $40.00 |
| 2 | Apply Priority 2 (10% off) | 10% of $40.00 = $4.00 discount | $36.00 |
| 3 | Apply Priority 3 ($5.00 off) | $36.00 - $5.00 discount | $31.00 |
Final Price: $31.00 (Total Discount: $19.00)
API Response Structure for Applied Promotions
On all basket and checkout related endpoints, the item object will no longer use a single promotion attribute. Instead, all applied promotions will be detailed within the promotions array attribute.
Sample Payloads
The following payload is a sample payload for a basket that contains one item with multiple promotions.
{
"id": "197fd144136440c721b041cde000d449",
"brand": {
"id": 1856,
"name": "AT"
},
"imageUrl": "https:\/\/next-qa.cdn.scayle.cloud\/images\/084dace7d7ff691e97982fa554113c29",
"pdpUrl": "https:\/\/next-qa.checkout.api.int.scayle.cloud\/product-192362",
"categories": [
{
"id": 1108,
"name": "CheckoutCategory"
}
],
"discount": {
"sale": 20000,
"saleWithoutTax": 16667,
"campaign": 3750,
"campaignWithoutTax": 3125,
"promotion": 8450,
"voucher": 0,
"voucherWithoutTax": 0,
"total": 32200
},
"displayData": {
"identifier": {
"value": "BCO-V-cyan-1234504433",
"label": {
"translationKey": "identifier"
}
},
"meta": {
"value": "AT",
"label": {
"translationKey": "meta"
}
},
"name": {
"value": "getStocks-t005-composite",
"label": {
"translationKey": "name"
}
}
},
"isQuantityChangeDisabled": false,
"merchant": {
"id": 1,
"variantId": "BCO-V-cyan-1234504433"
},
"name": "getStocks-t005-composite",
"productId": 192362,
"quantity": 1,
"styleKey": "BCO-P-orange-3666861502_master",
"total": {
"costWithTaxWithoutDiscount": 35000,
"costWithTaxWithDiscount": 2800,
"costWithoutTaxWithoutDiscount": 34533,
"costWithoutTaxWithDiscount": 2333
},
"unit": {
"costWithTaxWithoutVoucher": 2800,
"costWithoutTaxWithoutVoucher": 2333,
"taxWithoutVoucher": 467,
"taxRate": 20
},
"variantId": 294709,
"warehouseId": 1,
"promotion": [
{
"id": "68c155086f78638a50ee1ed8",
"version": "6ace2c2494e870e579ba5b03",
"discount": "5250",
"displayName": "Combo Deal"
},
{
"id": "6a95aed222e6d0028040024f",
"version": "6ace28c8237196e5557bdd1e",
"discount": "0",
"displayName": "BuyXGetY"
},
{
"id": "6a62ab044ea39d1d5a317ac1",
"version": "6ace2938237196e5557bdd20",
"discount": "1200",
"displayName": "Auto Discount 1"
},
{
"id": "6a676b76bb4e0ebfafa0b331",
"version": "6ace2b3f94e870e579ba5b01",
"discount": "2000",
"displayName": "Winter Discount"
}
],
"discounts": [
{
"amount": {
"withTax": 20000,
"withoutTax": 16667
},
"type": "sale",
"isEffective": true
},
{
"amount": {
"withTax": 3750,
"withoutTax": 3125
},
"type": "campaign",
"isEffective": true
},
{
"amount": {
"withTax": 5250,
"withoutTax": 4375
},
"type": "promotion",
"id": "68c155086f78638a50ee1ed8",
"name": "Combo Deal"
},
{
"amount": {
"withTax": 1200,
"withoutTax": 1000
},
"type": "promotion",
"id": "6a62ab044ea39d1d5a317ac1",
"name": "Auto Discount 1"
},
{
"amount": {
"withTax": 2000,
"withoutTax": 1667
},
"type": "promotion",
"id": "6a676b76bb4e0ebfafa0b331",
"name": "Winter Discount"
}
]
},
You can fin the promotion under variant ID ➜ discounts. Every applied promotion will show as follows:
Example price campaign or sale:
Promotion example:
- amount is expressed in cents (2000 is €20,00). You can find both balues with and without tax.
- type describes the type of the promotions. Available types:
- Sale
- Campagn
- Promotion
- isEffective is only available for sales and price campaigns.
- isEffective true means: the item's current payable price is lower than the
lowestPrioPricerecorded within the last 30 days. - isEffective false means: Either the item's price has not changed, or its current payable price remains equal to or higher than the
lowestPrioPricerecorded within the last 30 days, even after applying a sale, campaign, voucher, promotion, or LP.
- isEffective true means: the item's current payable price is lower than the
- id is only available for type promotion. These ids are assigned to a promotion uppon creation and can be consulted, in for exmaple, Panel. They can also be used directly on Panel's URL to edit a promotions
- name stands for Display Name.
Finally under promtions you will be able to see if any promotion is available for a certain items but was not applied as the item / basket did not meet the application criteria for such an items. For exmaple this Buy X Get Y promotion:
Certain promotion types are applied on basket, for example Free shipping. In this case this poromotion will be visible on the following part of the basket Payload:
"promotionDiscounts": [
{
"id": "68c155086f78638a50ee1ed8",
"name": "Combo Deal",
"discount": 10500
},
{
"id": "6a95aed222e6d0028040024f",
"name": "BuyXGetY",
"discount": 1500
},
{
"id": "6a62ab044ea39d1d5a317ac1",
"name": "Auto Discount 1",
"discount": 3876
},
{
"id": "6a676b76bb4e0ebfafa0b331",
"name": "Winter Discount",
"discount": 6000
},
{
"id": "6a62a1234ea39d1d5a317963",
"name": "Free Shipping Code",
"discount": 1990
}
],
- id is only available for type promotion. These ids are assigned to a promotion uppon creation and can be consulted, in for exmaple, Panel. They can also be used directly on Panel's URL to edit a promotions
- name stands for Display Name.
- discount is expressed in cents (2000 is €20,00)
