Develop > Presentation layer > Customize promotions > Promotion engine customization
Purchase condition XML definition
The purchase condition defines what customers must have in their shopping cart before they qualify for a promotion. If the order qualifies, the purchase condition defines the applicable reward. The purchase condition XML is part of the runtime promotion XML, which the promotion engine uses to evaluate promotions during the shopping flow.
High level elements
The purchase condition defines the following elements of a promotion:
- The pattern that the catalog entries in the shopping cart must match before the promotion is applied to the order.
- The reward that the customer receives when the required pattern is met.
PurchaseCondition element
The PurchaseCondition element is one of the primary elements inside the runtime promotion XML, and it defines the purchase condition. However, when creating a custom purchase condition, you are actually concerned with creating or customizing the elements inside the PurchaseCondition element, rather than the element itself.
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.condition.PurchaseCondition class.
The PurchaseCondition element contains one Pattern element and one Distribution element.
Pattern element
The Pattern element is one of the two primary elements inside the Purchase Condition element. The Pattern element contains the elements that define the things that a customer must have in their shopping cart to qualify for the promotion. This element is not very interesting, and serves to differentiate the elements from the reward elements.
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.condition.Pattern class.
A Pattern element contains one or more Constraint elements.
Constraint element
The Constraint element is the only element inside the Pattern element, though there may be multiple Constraint elements. The Constraint element contains elements that specify a list of items that make up one part of the pattern. There must be no cross-sections between constraints. Again, this element is not very interesting on it's own.
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.condition.Constraint class.
A Constraint element contains a WeightedRange element and a FilterChain element.
WeightedRange element
The WeightedRange element defines the quantity requirement of the Constraint.
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.condition.WeightedRange class.
A Constraint element contains XML similar to the following sample which defines the range. This sample illustrates a range the extends from 1 to infinity.
<LowerBound>1</LowerBound> <UpperBound>-1</UpperBound> <Weight>1</Weight>The LowerBound and UpperBound elements can contain any positive number or -1. The significance of -1 is that it means that the value is unbound. For example, setting the upper bound to -1 means that the range extends from the lower bound to infinity.
FilterChain element
The FilterChain element contains one or more filters that apply for the Constraint.
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.condition.FilterChain class.
A FilterChain element contains one or more filter definition XML elements which define the applicable filters. The generic filter displayed here as an example returns everything that it is passed.
<Filter impl="com.ibm.commerce.marketing.promotion.condition.DummyFilter"/>By setting the impl parameter you specify the applicable filter. The list of valid default filters, as well as any additional configuration XML they require can be found in the Example: Filter XML fragments topic.
Distribution element
The Distribution element is one of the two primary elements inside the Purchase Condition element. The Distribution element contains the elements that define the reward that a customer receives if they qualify for the promotion. This element is not very interesting, and serves to differentiate the elements from the pattern elements.
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.reward.Distribution class.
A Distribution element contains the following XML which defines the distribution method:
<Type>Volume</Type> <Base>Cost</Base> <Currency>CAD</Currency>The Type element determines the type of the distribution. The valid values are Volume and Tiered. The Base element determines whether the distribution is based on quantity or cost. The valid values are Quantity and Cost. The Currency element defines the currency in which cost-based distributions are evaluated. The valid values include the ISO codes for any currency supported in the store, but most often should be the store's default currency. The Currency element is meaningless for quantity-based distributions.
A Distribution element also contains a PatternFilter element and one or more Range elements.
PatternFilter element
The PatternFilter element determines the pattern of the reward.
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.condition.DummyFilter class.
Not all matched patterns are rewarded, for example, a combination of shirts and pants priced over $120 if a combination of shirts and pants which is priced at $100, it should be eliminated.
Range element
The Range element defines the range to which the subsequent adjustment applies. The range element requires XML similar to the following example. Similar to the WeightedRange element, this defines the applicable range by using an upper and lower boundary.
<UpperBound>200</UpperBound> <LowerBound>100</LowerBound>
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.reward.DistributionRange class.
The Range element contains a Reward element.
Reward element
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.reward.DefaultReward class.
The Reward element contains an AdjustmentFunction element.
AdjustmentFunction element
This element has an impl parameter which in almost every case should be set to the default value, which refers to the com.ibm.commerce.marketing.promotion.reward.AdjustmentFunction class.
The AdjustmentFunction contains a FilterChain element and an Adjustment element.
Adjustment element
The Adjustment element defines the adjustment to the customer's order. This could be a price adjustment to an catalog entry, an adjustment to the order price, a free gift, or other such adjustment.
This element has an impl parameter which corresponds to the adjustment that is being applied to the order. The list of valid default adjustments, as well as any additional configuration XML they require can be found in the Example: Adjustment XML fragments topic.
<PurchaseCondition impl="com.ibm.commerce.marketing.promotion.condition.PurchaseCondition"> <Pattern impl="com.ibm.commerce.marketing.promotion.condition.Pattern"> <Constraint impl="com.ibm.commerce.marketing.promotion.condition.Constraint"> <WeightedRange impl="com.ibm.commerce.marketing.promotion.condition.WeightedRange"> <LowerBound>1</LowerBound> <UpperBound>-1</UpperBound> <Weight>1</Weight> </WeightedRange> <FilterChain impl="com.ibm.commerce.marketing.promotion.condition.FilterChain"> <Filter impl="com.ibm.commerce.marketing.promotion.condition.DummyFilter"/> </FilterChain> </Constraint> </Pattern> <Distribution impl="com.ibm.commerce.marketing.promotion.reward.Distribution"> <Type>Volume</Type> <Base>Cost</Base> <Currency>CAD</Currency> <PatternFilter impl="com.ibm.commerce.marketing.promotion.condition.DummyPatternFilter" /> <Range impl="com.ibm.commerce.marketing.promotion.reward.DistributionRange"> <UpperBound>200</UpperBound> <LowerBound>100</LowerBound> <Reward impl="com.ibm.commerce.marketing.promotion.reward.DefaultReward"> <AdjustmentFunction impl="com.ibm.commerce.marketing.promotion.reward.AdjustmentFunction"> <FilterChain impl="com.ibm.commerce.marketing.promotion.condition.FilterChain"> <Filter impl="com.ibm.commerce.marketing.promotion.condition.DummyFilter" /> </FilterChain> <Adjustment impl="com.ibm.commerce.marketing.promotion.reward.FixedAmountOffAdjustment"> <AmountOff>15</AmountOff> <Currency>CAD</Currency> <AdjustmentType>wholeOrder</AdjustmentType> </Adjustment> </AdjustmentFunction> </Reward> </Range> <Range impl="com.ibm.commerce.marketing.promotion.reward.DistributionRange"> <UpperBound>-1</UpperBound> <LowerBound>200</LowerBound> <LowerBoundIncluded>false</LowerBoundIncluded> <Reward impl="com.ibm.commerce.marketing.promotion.reward.DefaultReward"> <AdjustmentFunction impl="com.ibm.commerce.marketing.promotion.reward.AdjustmentFunction"> <FilterChain impl="com.ibm.commerce.marketing.promotion.condition.FilterChain"> <Filter impl="com.ibm.commerce.marketing.promotion.condition.DummyFilter"/> </FilterChain> <Adjustment impl="com.ibm.commerce.marketing.promotion.reward.FixedAmountOffAdjustment"> <AmountOff>45</AmountOff> <Currency>CAD</Currency> <AdjustmentType>wholeOrder</AdjustmentType> </Adjustment> </AdjustmentFunction> </Reward> </Range> </Distribution> </PurchaseCondition>