Promotions

This area is subject to change, and will be reworked. Refer to Marketing [BETA] for more information.

Introduction

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 referred to here are available in the following namespaces:

• Mediachase.Commerce.Orders
• Mediachase.Commerce.Workflow.Activities.Cart
• Mediachase.Commerce.Website.Helpers

How it works

Promotions are applied to individual SKUs as well as Carts. 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 will calculate promotions that are specific to an individual SKU (for instance buy SKU x, get $y off), if any exist.

This method simply returns the discounted price for that SKU. It does not include quantity-based promotions for the SKU (for instance buy 3 SKU xs and get %20 off the SKU price) and does not include order-wide promotion discounts (for instance 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().

Promotions are also applied to a whole cart during checkout. This occurs in the 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 order 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:

• LineItem.LineItemDiscountAmount - total decimal amount of all promotions applicable to that LineItem.
• LineItem.LineItemDiscounts - which store a collection of promotions, including names of each promotiona and the amount.
• LineItem.OrderLevelDiscountAmount - amount of discount applicable from the order. This is applies when the Promotion RewardType is for the whole order and the promotion group is not shipping.
• LineItem.OrderLevelDiscounts - same as LineItemDiscountAmount except for promotion discounts applicable on the order level to an individual LineItem.
• Shipment.ShippingDiscountAmount - same as LineItemDiscountAmount except for promotion discounts applicable to a Shipment.
• Shipment.Discounts - same as LineItemDiscounts except for shipments.
• OrderForm.DiscountAmount - same as LineItemDiscountAmount except for promotion discounts applicable to the order as a whole, for instance $50 off an order when certain conditions are met.
• OrderForm.Discounts - same as LineItemDiscounts except for the entire order.

The CalculateDiscountActivity performs the discount calculations in the CalculateDiscounts() method.

After the CalculateDiscountActivity activity is run, the CalculateTotalsActivity calculates the totals for each lineitem, orderform, and shipment.

It performs these calculations to apply discounts:

• The LineItem.ExtendedPrice is calculated by multiplying the ListPrice for a SKU by the quantity being purchased and then subtracting the LineItemDiscountAmount and OrderLevelDiscountAmount.
• The OrderForm.SubTotal is the sum of the SKUs price, in this case PlacedPrice times the Quantity minus the LineItemDiscountAmount.
• The OrderForm.Total is the sum of the subtotal, shipping charges, taxes, minus the shipping discounts and LineItem order level discounts.

Expressions

Expressions is a core technology behind Marketing system. It allows for a very flexible and standards based way to extend different aspects of the system. Promotions, Customer Segments and Policies all rely on expressions. The architecture of Expression Manager is similar to the Provider model used in .NET Framework. The engine relies on external class to process the expression which can be specified in the configuration file. That class simply needs to implement IExpressionValidator interface and the actual implementation is up to that class.

With EPiServer Commerce we provide an implementation that relies on Windows for Workflow Foundation Rules Engine, so if you pick that you can use our Expression Editor to create expressions. The Expression Editor is located in the following path of your solution: BusinessLayer\MarketingSystem\ExpressionEditor

Refer also to Introduction to the Windows Workflow Foundation Rules Engine for more information.

Promotion rules engine

EPiServer Commerce includes a Promotion Rules Engine designed to provide a flexible and fast framework to create different types of promotions that will be displayed on the front-end.

The Promotion Engine has two distinct use cases:

• Design mode: to configure promotions
• Runtime mode: to display and apply promotions

Design mode

Promotions are created either using the graphical user interface in the administration console or by a developer. Most of the promotions can be created by using "Custom Promotion" type, which you can select when creating new promotion. In cases where promotions are very specific, a developer may need to create custom expressions and user interfaces.

There are three groups of promotions which determine in which scenario they are executed:

• CatalogEntry - executed against individual entry and can be applied to the items in the catalog and shown during search, catalog browsing.
• Order - executed against the whole order and will only display on the shopping cart/order pages.
• Shipping - executed against individual shipments and will be shown only on the order/checkout pages.

Runtime mode

There are two distinct ways the promotions are applied to the product: during browsing or searching of catalog, and when 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:

1. Checks global exclusivity (if a global promotion has been applied, the execution stops).
2. Checks target group.
3. Checks group exclusivity.
4. Checks limits (applied only once).
5. Checks dates and status.
6. Verifies coupon.
7. Performs basic catalog/node/entry filtering.
8. Checks conditions (expressions).
9. Checks policies.
10. Commits all new records (promotions added).

Browsing catalog

During catalog browsing you would typically use relatively simple promotions that just apply to the individual products.

Catalog browsing execution sequence:

1. StoreHelper.GetDiscountPrice(Entry entry, string catalogName)
2. PromotionHelper.Eval(PromotionFilter filter)
3. MarketingContext.Current.EvaluatePromotions(true, this.PromotionContext, filter)

Step 1

During step 1 we get the sale price, which will be used to calculate the base price for which discounts if any will be added.

Example: getting the sale price

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);

Next we need to setup the PromotionContext, which will provide context for our rules to execute against. Since there is just one product in this case, all we need to do is to 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:

• MarketingContext - this is where we add extra objects that can be used by the expression engine.
• TargetGroup - we set it to the entry, since this is the only promotion group we should be executing when browsing catalogs.
• IPromotionEntryPopulate - this is an interface that allowsfor overriding how the properties are copied from Entry object to the PromotionEntry object. This is configured in the ecf.marketing.config file using PromotionEntryPopulateFunctionType config section. This is set to "Mediachase.Commerce.Marketing.Validators.PromotionEntryPopulate,Mediachase.Commerce.Marketing.Validators" by default.

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;

Step 2

During step 2 we simply execute the promotion engine with all the information collected during step 1.

Example: executing the promotion engine

MarketingContext.Current.EvaluatePromotions(true, this.PromotionContext, filter);

Step 3

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 the items affected and the discount applied.

Cart checkout

During checkout more complex promotions can be used. In this case you are working in the context of the order system. You will no longer calculate discount directly, but through the use of workflow activities.

Execution sequence:

1. CartHelper.RunWorkflow("CartValidate") CalculateDiscountsActivity.
2. CalculateDiscounts

Step 1

In this step you initiate the workflow. Typically the workflow will check if entries exist and are available, remove all the existing discounts and then execute the CalculateDiscountsActivity. This will be done during each step in the checkout process or when accessing the shopping cart.

Step 2

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 and 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);

EffectiveCustomerGroup

This read-only property of the CustomerContact class is the actual customer group used by the promotion engine in both determining 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.

See also

• Customers