While Product Discounts apply to a Product Variant Price record, Cart Discounts apply to a Customer's Cart when a Line Item is added to it. Each time a change is made to a Cart, such as adding or removing a Line Item, the Cart Discounts are recalculated. The Project-level DiscountCombinationMode determines whether Product Discounts and Cart Discounts both apply (Stacking) or only the discount type offering the best deal applies (BestDeal).
You can create two types of Cart Discounts:
- Numeric: A Cart Discount that applies either a relative discount (a percentage off), an absolute discount (a set amount off), or a fixed price discount (for example, get 3 watermelons for $5) after items are added to the Cart.
- Gift line item: A Cart Discount that adds a specific Product to the Cart after items are added to the Cart.
You can find directions to create either Numeric or Gift line item Cart Discounts in the documentation.
The number of active Cart Discounts you can have is
100. In addition to this 100, you can also have a further 100 Cart Discounts associated with a specific Store, per Store. So in total, your limit for Cart Discounts is 100 + (100 * number of Stores in a Project). The number of Stores configured for a Cart Discount is limited to 500.These limits do not apply to Cart Discounts attached to Discount Codes, which have separate limits.
Set up Cart Discounts in the Merchant Center
The Merchant Center provides a UI to set up your Cart Discounts that follows a similar pattern no matter the type of Cart Discount you are setting up:
-
General information
-
Discount configuration
- Under these cart conditions: (Cart Discount condition)
- Apply these discount effects: (Cart Discount effect)
You can find more information on how to work with the UI on the Merchant Center Cart Discounts page in the docs. Our use cases on the following pages will stick to this structure when we work through how to set up our various Cart Discounts.
Like Product Discounts, Cart Discounts also use predicates. In fact, Cart Discounts use two types of predicates; Cart Discount conditions and Cart Discount effects.
Cart Discount conditions
A Cart Discount condition is very similar to the predicate we used with Product Discounts. You can create these visually in the Merchant Center and the section in the UI you use to create this predicate is labeled Under these cart conditions.
A Cart Discount condition can utilize a lot more identifiers than you can use in a Product Discount predicate. For a Cart Discount condition, you refer to things within the Cart context. For example, you can refer to information about the Cart itself – the Country or Currency or fields in the Shipping Address like Postal Code. You can refer to things about the Customer that owns the Cart – like their Customer Group. You can also use specific functions, for example the
lineItemExists function which returns true or false if there is at least one LineItem in the cart that matches the parameters passed to the functions. You can find a lot more detail about the fields available to you in the Carts Predicate section of our documentation.Cart Discount effects
A Cart Discount effect defines which segment of the Cart will be discounted; there are four options that you can choose from. When you select an option, it targets its discount to:
- Total Price: the total Price of the Cart.
- Item: can target either a Line Item (a snapshot of a Product Variant at the time it is added to a Cart), or a Custom Line Item (a generic item not associated to any Product Variant). See Line Items and Custom Line Items for further information about the difference between these two.
- Multibuy line items: represent a "Buy X items, get Y of them at a discounted rate" type of discount. Can also be used either with Line Items or Custom Line Items. Please note multibuy discounts can only receive a relative (%) discount.
- Shipping: the Cart’s shipping costs.
For each of these, except Shipping costs, the predicate you build to define these conditions is much like the one for building the Cart Discount condition. In the Merchant Center, the section you use to create the Cart Discount Target is labeled Apply these discount effects.
Remember that there are two possibilities to offer free shipping to customers: through using Free above in Shipping Methods, and Cart Discounts. We strongly recommend using only one option in your Project. Please review Free shipping thresholds for more detail.
Discount combination modes
The Project's DiscountsConfiguration controls how Product Discounts and Cart Discounts interact when both apply to a Cart. This configuration determines your Project's discount strategy: maximize savings by stacking both discount types, or simplify calculations by applying only the best deal.
Stacking mode
When
discountCombinationMode is set to Stacking, both Product Discounts and Cart Discounts apply sequentially. The platform applies Product Discounts first (reducing Line Item prices), then applies Cart Discounts to the already-reduced prices. This maximizes customer savings but increases discount calculation complexity.When to use:
- Customer acquisition campaigns where maximum savings drive conversions
- Loyalty programs offering cumulative benefits
- Promotional periods where stacking multiple offers is acceptable
Trade-offs:
- Higher discount costs (both types apply)
- More complex discount planning (interactions between discount types)
- Cart total calculations require understanding both discount types
BestDeal mode
When
discountCombinationMode is set to BestDeal, the platform calculates Cart totals twice—once with Product Discounts, once with Cart Discounts—then applies whichever discount type yields the lower total. Only one discount type applies per Cart, indicated in the discountTypeCombination field.When to use:
- Controlled discount budgets where stacking would be too costly
- Simplified discount strategies with predictable costs
- Business rules requiring only one discount type per order
Trade-offs:
- Lower discount costs (only one type applies)
- Simpler discount planning (no interaction complexity)
- May result in higher prices for some Line Items if best deal requires switching discount types
Configuration
Set the discount combination mode in Project settings via the Merchant Center, or use the Set Discounts Configuration update action:
{
"action": "setDiscountsConfiguration",
"discountsConfiguration": {
"discountCombinationMode": "BestDeal"
}
}
The mode affects all Carts in the Project. Default is
Stacking if not configured.Ranking and stacking
Like Product Discounts, all Cart Discounts must have a rank – for Cart Discounts this is important as a Cart can have more than one Discount applied at any given time.
Rank determines the processing order of Cart Discounts, which impacts the final Cart total. Set rank to control discount application order.
Example: Consider a Cart with a subtotal of $100 and two Cart Discounts:
- Discount A (rank 0.1): 10% off the total
- Discount B (rank 0.2): $5 off the total
Since Discount A has a lower rank, it applies first: $100 - 10% = $90. Then Discount B applies: $90 - $5 = $85 final total.
If the ranks were reversed (B at 0.1, A at 0.2), the final total would be: $100 - $5 = $95, then $95 - 10% = $85.50. The rank order can affect the final price when combining percentage and fixed discounts.
In addition to rank, a Cart Discount has a
stackingMode field controlling whether additional Cart Discounts can apply after this one. This is distinct from the Project-level discountCombinationMode (which controls Product/Cart Discount interaction). The Cart Discount stackingMode values are Stacking (continue processing other Cart Discounts) and StopAfterThisDiscount (prevent further Cart Discounts from applying).In the Merchant Center, the Stacking Mode is presented like this:
This image indicates a Cart Discount with
StackingMode set to StopAfterThisDiscount.When other Cart Discounts with different effects apply on a Cart, a Total Price discount applies last, regardless of its sort order and ignoring the
As a result, the
StopAfterThisDiscount StackingMode of the other Cart Discounts, if any. The sort order for the Total Price discount only determines its ranking among other Cart Discounts targeting the Total Price.As a result, the
stackingMode = StopAfterThisDiscount takes effect for a Cart Total Price discount only when there are other Cart Discounts targeting the Total Price with a lower sort order.