Skip to main content

Applying Promotions

Before a promotion can be applied to a cart, it must pass all of these checks:

  1. Its schedule is active at the time of the sale, and the sale's location is in its EnabledAtLocationIds.
  2. Its cart conditions pass.
  3. Its line conditions and product conditions pass for the line items it uses.

How the promotion's discount is then applied depends on its promotion type.

Buckets and consumption​

Promotions work with buckets of products. A bucket is a group of products, at some quantity, that are included in the promotion together. It could be many of one product, or one each of many products, depending on the promotion.

Generally, a promotion has a bucket of products that are consumed to apply it, and a bucket of products that get the discount. These may or may not be the same bucket:

  • A CheapestMatchedFor promotion has a single bucket, and the cheapest product in it gets the discount.
  • A MatchThenCheapestOtherFor promotion has one bucket of products required to fulfil the promotion, and a different bucket of products that can get the discount.

Once a product is used to apply a promotion, or is discounted by one, it's consumed and can't be used for any other promotion.

Discounts​

How to apply each promotion type is implied by its name, which is made of the kind of promotion and the kind of discount. The kinds of promotion are explained below, from simplest to most complex.

EachMatched​

The EachMatched types are the simplest. There's a single bucket containing every product that matches ItemsToMatch, and every product in it gets the discount. Unlike the other types, there's no quantity requirement.

These types are equivalent to, or at least mappable from, Cova's older promotion types.

DiscountApplied as
DollarOffEach product is discounted by DollarOffOfEach. Use GramsPerMatchUnit to convert gram-based products to each-based ones so the dollar amount is applied correctly.
PercentOffEach product is discounted by PercentOffOfEach: 0.3 means 30% off. GramsPerMatchUnit isn't needed, since a percentage applies regardless of quantity.

CheapestMatchedFor​

CheapestMatchedFor types have a single bucket of products that match ItemsToMatch. Once the bucket has NumberToMatch products (using GramsPerMatchUnit to count gram-based products), the promotion applies, and the cheapest product in the bucket gets the discount.

DiscountApplied as
DollarThe cheapest product is charged DollarValueOfCheapest.
DollarOffThe cheapest product is discounted by DollarOffOfCheapest.
PercentOffThe cheapest product is discounted by PercentOffOfCheapest.

Line items are consumed most expensive first. The discount then goes to the cheapest product available.

Example​

All five of these products pass the promotion's ItemsToMatch conditions:

ProductPrice
Product A$10
Product B$9
Product C$8
Product D$7
Product E$6

The promotion is a CheapestMatchedForDollar with a NumberToMatch of 3 and a DollarValueOfCheapest of $1. Three products are included in the promotion:

  • Products A and B, the most expensive, are consumed and don't get a discount.
  • Product E, the cheapest, is consumed and sold for $1.
  • Products C and D aren't consumed, and can be used for other promotions.

If NumberToMatch is 2 instead, the promotion applies twice, so two products are discounted (unless MaxApplicationCount is 1, which limits it to one application):

  • The first application consumes Products A and E, and Product E is sold for $1.
  • The second application consumes Products B and D, and Product D is sold for $1.
  • Product C isn't consumed, and can be used for other promotions.

MatchThenCheapestOtherFor​

MatchThenCheapestOtherFor types are like CheapestMatchedFor, but with two condition trees: one for the products that enable the promotion, and another for the products that can get its discount.

  • MatchConditions is the tree that a quantity of products must meet to enable the discount.
  • OtherItemConditions is the tree that a product must meet to receive the discount.

Once NumberToMatch products (using GramsPerMatchUnit to count gram-based products) meet MatchConditions, the cheapest product that meets OtherItemConditions and wasn't already consumed by MatchConditions gets the discount. The discounts are the same as for CheapestMatchedFor:

DiscountApplied as
DollarThe product is charged DollarValueOfOther.
DollarOffThe product is discounted by DollarOffOfOther.
PercentOffThe product is discounted by PercentOffOfOther.

OtherItemConditions only ever applies to a single quantity of a product. Use GramsPerMatchUnit to convert a gram-based product into an each-based one.

As with CheapestMatchedFor, products are consumed most expensive first to meet MatchConditions, and cheapest first when finding the product to discount.

BundleFor​

BundleFor types contain a list of BundleMatch elements in BundleItemsToMatch. Each element has its own product condition tree and quantity, so a bundle can have different requirements for each of its elements.

An element of the bundle is any product matching the element's ProductCondition, at the required QuantityToMatch. Use GramsPerMatchUnit to convert gram-based quantities into each-based ones.

Once the cart has enough of every element in BundleItemsToMatch, the discount applies to every item in the bundle:

DiscountApplied as
TotalDollarDistributedThe bundle's total price, DollarValueOfAll, is distributed across all the items in the bundle in proportion to their original prices.
TotalDollarOffDistributedThe discount, DollarOffOfAll, is taken from all the items in the bundle in proportion to their original prices.
PercentOffEach item in the bundle is discounted by PercentOffOfAll.