Five New Optimizely Certifications are Here! Validate your expertise and advance your career with our latest certification exams. Click here to find out more
Five New Optimizely Certifications are Here! Validate your expertise and advance your career with our latest certification exams. Click here to find out more
A promotion is a marketing tool used to increase sales of certain products or product lines. Promotions provide a way to apply various discounts to the products, order totals, or shipping.
Classes in this topic are available in the following namespaces:
You can apply a promotion to an individual SKU or Cart. The PublicLayer/WebUtility/Helpers/StoreHelper.cs class (Mediachase.Commerce.Website.Helpers namespace) provides a convenient means to determine the discounted price for an SKU using the GetDiscountPrice() method. This calculates promotions that are specific to an individual SKU (such as buy SKU x, get $y off), if any exist.
GetDiscountPrice() returns the discounted price for an SKU but does not include quantity-based promotions for the SKU (such as buy 3 SKU xs and get %20 off the SKU price) and does not include order-wide promotion discounts (such as if your cart subtotal before taxes and shipping is over $100, shipping is free). The StoreHelper calls the promotion engine to calculate the price for a SKU by calling PromotionHelper.Eval().
You also can apply a promotion to a whole cart during checkout using CalculateDiscountActivity.cs in the BusinessLayer/OrderSystem/ActivityLibrary project (Mediachase.Commerce.Workflow.Activities.Cart namespace). This activity is included in two workflows: CartValidateWorkflow and CartPrepareWorkflow.
The CartValidateWorkflow is designed to calculate the subtotal for a cart, including promotions; the subtotal does not include calculating taxes and shipping charges. The CartPrepareWorkflow is designed to calculate the final state of a cart before the customer confirms the purchase, including taxes and shipping charges. Discounts are set in the cart by setting discount properties and calculating the cart total with deductions for the discounts.
The discount properties include:
The CalculateDiscountActivity performs the discount calculations in the CalculateDiscounts() method.
After the CalculateDiscountActivity activity runs, the CalculateTotalsActivity calculates the totals for each LineItem, OrderForm, and Shipment. It performs the following calculations to apply discounts:
Expressions, core technology behind the marketing system, allow flexible and standards-based ways of extending different aspects of the system. Promotions, Customer Segments and Policies rely on expressions. The architecture of Expression Manager is similar to the Provider model used in .NET Framework. The engine relies on an external class to process the expression that you can specify in the configuration file. That class needs to implement the IExpressionValidator interface. The actual implementation is up to that class.
Episerver Commerce has an implementation that relies on Windows for Workflow Foundation Rules engine, so if you pick that, you can use the Episerver Expression Editor to create expressions. The Expression Editor is located in BusinessLayer\MarketingSystem\ExpressionEditor in your solution. See also Introduction to the Windows Workflow Foundation Rules Engine.
Episerver Commerce includes a Promotion Rules Engine designed to provide a flexible and fast framework to create different types of promotions that are displayed on the front-end.
The Promotion Engine has two distinct use cases:
You can create a promotion using the graphical user interface in the administration console or by API. You can create most promotions by selecting the Custom Promotion type. In cases where promotions are very specific, a developer may need to create custom expressions and user interfaces.
The following groups of promotions determine in which scenario they are executed:
There are two distinct ways the promotions are applied to the product: while browsing or searching the catalog, and while viewing a shopping cart or checking out. They both rely on the MarketingContext.EvaluatePromotions method, which cycles through each promotion, prioritizing and filtering them.
The execution sequence for EvaluatePromotion is as follows:
During catalog browsing, you typically use relatively simple promotions that apply to individual products only.
Catalog browsing execution sequence:
During step 1, get the sale price used to calculate the base price for which discounts (if any) are added.
C#
decimal minQuantity = 1;
// get min quantity attribute
if (entry.ItemAttributes != null)
minQuantity = entry.ItemAttributes.MinQuantity;
// we can't pass qauntity of 0, so make it default to 1
if (minQuantity <= 0)
minQuantity = 1;
// Get sale price for the current user
Price price = StoreHelper.GetSalePrice(entry, minQuantity);
Note: Minimum quantity is passed when browsing the item in the catalog, which typically defaults to 1.
Next, set up the PromotionContext, which provides context for rules to execute against. Because there is just one product in this case, create a new PromotionEntry object, which represents one product for our marketing system, and populate it with all the attributes (meta-fields from the catalog entry) that might be used during promotion evaluation.
Other key concepts during this stage are:
Example: creating PromotionEntry object
// Create new promotion helper, which will initialize PromotionContext object for us and setup context dictionary
PromotionHelper helper = new PromotionHelper();
// Get current context
Dictionary<string, object> context = MarketingContext.Current.MarketingProfileContext;
// Create filter
PromotionFilter filter = new PromotionFilter();
filter.IgnoreConditions = false;
filter.IgnorePolicy = false;
filter.IgnoreSegments = false;
filter.IncludeCoupons = false;
// Create new entry
PromotionEntry promotEntry = new PromotionEntry(catalogName, String.Empty, entry.ID, price.Amount);
// Populate entry parameters
((IPromotionEntryPopulate)MarketingContext.Current.PromotionEntryPopulateFunctionClassInfo.CreateInstance()).Populate(ref promotEntry, entry);
PromotionEntriesSet sourceSet = new PromotionEntriesSet();
sourceSet.Entries.Add(promotEntry);
// Configure promotion context
helper.PromotionContext.SourceEntriesSet = sourceSet;
helper.PromotionContext.TargetEntriesSet = sourceSet;
// Only target entries
helper.PromotionContext.TargetGroup = PromotionGroup.GetPromotionGroup(PromotionGroup.PromotionGroupKey.Entry).Key;
Example: calling the eval method and returning the discounted price
// Execute the promotions and filter out basic collection of promotions, we need to execute with cache disabled, so we get latest info from the database
helper.Eval(filter);
// Check the count, and get new price
if (helper.PromotionContext.PromotionResult.PromotionRecords.Count > 0)
return ObjectHelper.CreatePrice(price.Amount - GetDiscountPrice(helper.PromotionContext.PromotionResult), price.CurrencyCode);
else
return price;
Execute the promotion engine using all information collected during step 1.
Example: executing the promotion engine
MarketingContext.Current.EvaluatePromotions(true, this.PromotionContext, filter);
Goes through each promotion, checks the policies, customer segments, dates and validates the expressions. When the promotion is successfully applied, it is typically added to the PromotionResult object as a PromotionItemRecord object, which contains information about affected items and discounts applied.
During checkout, more complex promotions can be applied. Now, you are working in the context of the order system. You no longer calculate discount directly, but through the use of workflow activities.
Execution sequence:
Typically, the workflow checks whether entries exist and are available, removes existing discounts, then executes the CalculateDiscountsActivity. This occurs during each step in the checkout process or when accessing the shopping cart.
The logic of discounts activity is very similar to the one used during browsing, with exception of two additional discount groups: Order and Shipment. The engine first calculates line item discounts, then order, then shipments.
Example: calculating discount for each individual order form
#region Determine Order level discounts
foreach (OrderForm form in order.OrderForms)
{
// Now process global order discounts
// Now start processing it
// Create source from current form
sourceSet = CreateSetFromOrderForm(form);
promoContext.SourceEntriesSet = sourceSet;
promoContext.TargetEntriesSet = sourceSet;
promoContext.TargetGroup = PromotionGroup.GetPromotionGroup(PromotionGroup.PromotionGroupKey.Order).Key;
}
// Evaluate conditions
MarketingContext.Current.EvaluatePromotions(useCache, promoContext, filter);
#endregion
Example: IPromotionEntryPopulate interface
((IPromotionEntryPopulate)MarketingContext.Current.PromotionEntryPopulateFunctionClassInfo.CreateInstance()).Populate(ref entry, lineItem);
This read-only property of the CustomerContact class is the customer group used by the promotion engine to determine price and the CustomerGroup property one would use in a Customer Segment condition expression.
Refer to the Customers section in this documentation for more information about EffectiveCustomerGroup.
Last updated: Oct 12, 2015