Understanding the Promotion Evaluation Process
This guide explains how Deducto evaluates promotions when a cart is processed. Knowing the process helps you set up promotions that work together the way you intend, and work out why a promotion isn't applying.
When a cart is sent to Deducto, the engine sorts your promotions into a fixed order, then checks each one in turn to decide whether it applies.
TipYour project's
Promotionslist is sorted byEvaluation orderby default, so it shows your promotions in the order Deducto considers them. Promotions at the top are evaluated first, and what they do, such as discounting or locking items or stopping other promotions, can affect the promotions below them. It's a handy way to see how the rules in this guide apply to your own promotions.
Before evaluation
Before any promotion is considered, Deducto checks the request against your project's limits. If the cart has more lines than Cart items per evaluation, more shipping methods than Shipping methods per cart, or more coupon codes than the project allows, the whole request fails with an InvalidCartData error, and no promotions are evaluated. Cart lines are counted, not item quantities. You can change the cart item and shipping method limits under Promotion limits in your project's settings. See After creating the project in Creating a Project.
Promotion order
A cart can qualify for several promotions at once. For example, a customer buying three pairs of shoes might qualify for both "20% off shoes" and "buy 2, get 1 free". Deducto decides which is considered first, and whether they stack, using a fixed set of ordering rules.
First, Deducto collects every promotion that's turned on and could apply to the cart, and sorts them:
- Promotions set to
Only this promotion appliescome first, then everything else. Final deals can't use this setting, so they're never moved to the front. - Within each of those groups, product deals come first, then whole-order deals, then final deals.
- Within each type, higher
Prioritynumbers come first. - When type and priority match, the promotion ID breaks the tie.
That gives five groups, considered from left to right:
flowchart LR
A1["Only this promotion applies ·<br/>Product deals"] --> A2["Only this promotion applies ·<br/>Whole-order deals"]
A2 --> B1["Product deals"] --> B2["Whole-order deals"]
B2 --> C1["Final deals"]
Promotion evaluation and application
Once the promotions are sorted, Deducto checks each one in turn. The checks run in the order below. If one fails, the promotion is rejected and Deducto moves on to the next promotion.
Some rejections are reported in the response's rejectedPromotions, with a rejectionReason such as Stopped or PromotionUsageExceeded. These values are meant for debugging and for storefront logic that reacts to specific cases, not for showing to customers. Rejections from the currency, order condition and coupon checks aren't reported. This keeps the response focused on cases you can act on, and avoids revealing which coupon codes exist.
- Currency: the promotion must support the cart's currency. If it doesn't, the promotion is skipped without being reported.
- Order conditions: the cart must meet the promotion's order conditions. If it doesn't, the promotion is skipped without being reported.
- Coupon codes, for promotions that need one: the customer must have entered one of the promotion's codes, and that code must be enabled and under its own use limit. If not, the promotion is skipped without being reported.
- Usage limits: the promotion's
How many times can it be used in total?andHow many times per customer?limits are checked. When one has been reached, the response reportsPromotionUsageExceededorPromotionPerCustomerUsageExceeded, with the limit inusageCountLimit. On promotions that need a coupon code, the per-code limit is part of the coupon check instead. - Stop and Only this promotion applies: if an earlier promotion that applied was set to
Stop — don't apply anything elseorOnly this promotion applies, this promotion is rejected withStoppedorExclusivity. This check only applies to product deals and whole-order deals. Final deals are always checked. - Applied promotions limit: if the cart has already reached the project's limit on applied promotions, the promotion is rejected with
AppliedPromotionsLimitReached, and the limit is included in the response. - Reward: finally, the promotion's reward is applied to the cart. If it can't take effect, for example because no cart items match its product sets, the promotion is rejected with
NoApplicableCartItems.
If the reward is applied, the promotion is recorded as applied. On product deals, Don't let other promotions discount these items again then decides whether the items it used, both the discounted items and the items that qualified the cart, are still available to product deals considered later. Whole-order deals that take an amount off the order still spread that amount across locked items.
How product deals choose items
A product deal's product sets can often be filled from the cart in more than one way. Deducto tries the possible combinations and picks the one that gives the customer the biggest discount, or the one that discounts the cheapest items if Which items get the discount? is set to The cheapest items. See Rewards for product deals in Creating a Promotion.
After this promotion applies
The After this promotion applies setting decides what happens once a promotion has been applied:
Keep checking other promotionsmoves on to the next promotion in order, as if the setting weren't there.Stop — don't apply anything elseskips every product deal and whole-order deal considered after this one. Final deals can still apply.Only this promotion applieshas the same effect after the promotion applies, and also moves it to the front of the promotion order, so it's considered before any promotion without this setting.
Final deals always keep checking other promotions, and neither setting stops them. That's what makes them the right choice for free shipping or a free gift that should apply on top of every other discount.
Final results
Once every promotion has been checked, Deducto calculates the final totals and returns them to your storefront.
For each cart item, every discount that applied to it is combined into its discountedSubtotal. The response also lists each discount in discountSteps, so you can show or audit each one.
For each shipping method, only the best discount applies, so shipping promotions targeting the same method don't combine. The response shows the winning discount as bestDiscount on the shipping method, and discountedPrice shows the result.
Alongside the cart totals, the response includes:
appliedPromotions, the promotions that applied.rejectedPromotions, the promotions that were considered but didn't apply, where the reason is reported. Each has arejectionReason, plus any extra details for that reason, such asusageCountLimitorappliedPromotionsLimit. Promotions skipped by the currency, order condition and coupon checks aren't included.cartItemPromotions, the total discount each applied promotion gave the cart items, which is useful for showing a total per promotion. Shipping discounts aren't included, because they appear on the shipping method instead.couponMatchResults, which shows for each code the customer entered whether it wasvalid, whether it wasapplied, aninvalidReasonif it wasn't valid, and thetriggeredPromotionsit matched.
For the full response, see the Verify endpoint API reference or our Custom Storefront Integration guide.
Summary
Deducto evaluates promotions the same way every time. It sorts them, checks each one in a fixed sequence, applies or rejects it, then works out the totals. A few points often catch people out when troubleshooting:
Stop — don't apply anything elseandOnly this promotion appliesonly skip product deals and whole-order deals. Final deals still apply.- Shipping discounts don't combine. Each shipping method gets its single best discount.
Priorityonly orders promotions of the same type that also share the sameOnly this promotion appliessetting. A whole-order deal with priority100is still considered after a product deal with priority10, unless the whole-order deal is set toOnly this promotion appliesand the product deal isn't.
With those in mind, the response tells you what applied, what was rejected and, for most rejections, why. When a promotion is missing from both appliedPromotions and rejectedPromotions, either it was never evaluated, because it's turned off or outside its Starts and Ends dates, or it was skipped by the currency, order condition or coupon checks. Work through Promotion Not Applying to find which.
Updated 13 days ago