Product Discounts apply to a Product Variant Price record. Cart Discounts apply to a Customer's Cart when a Line Item is added. 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.
Cart Discounts are subject to a limit in a Project.
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 the full list of available identifiers, see Cart predicates in the API documentation.
Cart Discount effects
A Cart Discount effect defines which segment of the Cart will be discounted. There are four effect types: Total Price, Item, Multibuy line items, and Shipping. For descriptions of each, see CartDiscountTarget in the API documentation.
For each of these except Shipping costs, the predicate is similar to the Cart Discount condition predicate. In the Merchant Center, the section you use to create the Cart Discount Target is labeled Apply these discount effects.
Two options exist for offering free shipping: Free above in Shipping Methods, and Cart Discounts. We strongly recommend using only one option in your Project. For more detail, see Free shipping thresholds.
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 per discount type. It then applies whichever 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 on the Project resource. The
discountsConfiguration field accepts a DiscountsConfiguration object.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. The Cart Discount stackingMode is distinct from the Project-level discountCombinationMode (which controls Product/Cart Discount interaction). The 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.