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:
- We only allow ONE Buy X Get Y promotion to be applied for each item. In case more than one Buy X Get Y promotion effects apply to an item, the one with highest priority is applied.
- 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.
- In case the Basket configuration
basket.filter.price.disableZeroPrices=1, configured via the Config API, AND the promotion will make the item price go into 0, Scayle exposes the price of that item as 0,01 cents.
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.
