Customizing the shopping cart calculation

Default calculation pipeline

The default shopping cart calculation in Kentico uses a composite implementation of the IShoppingCartCalculator interface – the ShoppingCartCalculatorCollection class. The ShoppingCartCalculatorCollection accepts an IEnumerable collection of other IShoppingCartCalculator instances (steps), calls the Calculate method of each step, and passes the CalculatorData between the steps.

The default calculation pipeline consists of the following steps (each step is an IShoppingCartCalculator implementation):

Modifying the default calculation

You can use the ShoppingCartCalculatorCollection class to customize the shopping cart calculation while preserving the default calculation (or parts of it):

1. Prepare an IEnumerable collection of IShoppingCartCalculator instances. Define your own calculation pipeline, consisting of the default calculation steps and your own custom IShoppingCartCalculator steps.
2. Create and register a custom IShoppingCartCalculationFactory implementation.
3. Implement the GetCalculator method in the IShoppingCartCalculationFactory class and return an instance of the default ShoppingCartCalculatorCollection class, with the prepared IShoppingCartCalculator collection as the constructor parameter.

Example – Adding an extra charge calculation step

The following example demonstrates how to add a custom step to the shopping cart calculation, while preserving all of the default calculation logic. The step adds an extra charge to the total price of the shopping cart or order based on the selected payment option.

Prepare a separate project for custom classes in your Kentico solution:

1. Open your Kentico solution in Visual Studio.

2. Create a new Class Library project in the Kentico solution (or reuse an existing custom project).

3. Add references to the required Kentico libraries (DLLs) for the new project:

   1. Right-click the project and select Add -> Reference.

   2. Select the Browse tab of the Reference manager dialog, click Browse and navigate to the Lib folder of your Kentico web project.

   3. Add references to the following libraries (and any others that you may need in your custom code):

      • CMS.Base.dll
      • CMS.Core.dll
      • CMS.DataEngine.dll
      • CMS.Ecommerce.dll
      • CMS.Globalization.dll
      • CMS.Helpers.dll
      • CMS.Membership.dll

4. Reference the custom project from the Kentico web project (CMSApp or CMS).

5. Edit the custom project’s AssemblyInfo.cs file (in the Properties folder).

6. Add the AssemblyDiscoverable assembly attribute:

   Copy

   
   
   
    using CMS;
   
    [assembly:AssemblyDiscoverable]
   
   
    

Continue by creating custom implementations of the IShoppingCartCalculationFactory and IShoppingCartCalculator interfaces:

1. Add a new class under the custom project, implementing the IShoppingCartCalculator interface.

2. Implement the Calculate method to define the custom calculation logic that adds the extra charge to the shopping cart totals.

   Copy

   
   
   
    using CMS.Ecommerce;
    using CMS.Core;
   
    public class ExtraChargeShoppingCartCalculator : IShoppingCartCalculator
    {
        /// <summary>
        /// Runs shopping cart calculation based on specified calculation data.
        /// </summary>
        public void Calculate(CalculatorData calculationData)
        {
            CalculationRequest request = calculationData.Request;
            CalculationResult result = calculationData.Result;
   
            decimal extraCharge = 0;
   
            // Adds an extra charge of 5 (in the site's main currency) to the shopping cart totals
            // if the selected payment option's code name is 'custompayment'
            if (calculationData.Request.PaymentOption?.PaymentOptionName.ToLowerInvariant() == "custompayment")
            {
                extraCharge = 5m;
   
                // Uses the default Kentico currency API to convert the price
                // from the site's main currency into the requested currency (if necessary)
                ICurrencyConverterFactory currencyConverterFactory = Service.Resolve<ICurrencyConverterFactory>();
                ICurrencyConverter currencyConverter = currencyConverterFactory.GetCurrencyConverter(calculationData.Request.Site);
   
                string siteMainCurrencyCode = Service.Resolve<ISiteMainCurrencySource>().GetSiteMainCurrencyCode(calculationData.Request.Site);
                string currencyCode = calculationData.Request.Currency.CurrencyCode;
   
                extraCharge = currencyConverter.Convert(extraCharge, siteMainCurrencyCode, currencyCode);
            }
   
            result.Total += extraCharge;
            result.GrandTotal += extraCharge;
        }
    }
   
   
    

3. Add a new class under the custom project, implementing the IShoppingCartCalculationFactory interface.

4. Prepare an IEnumerable collection of IShoppingCartCalculator instances matching the default calculation steps, and add an instance of the custom ExtraChargeShoppingCartCalculator step to the end.

5. Implement the GetCalculator method in the IShoppingCartCalculationFactory class.

   • Return an instance of the default ShoppingCartCalculatorCollection class, with the prepared IShoppingCartCalculator collection as the constructor parameter.

using System.Collections.Generic;

using CMS;
using CMS.Ecommerce;
using CMS.DataEngine;

// Registers the custom implementation of IShoppingCartCalculationFactory
[assembly: RegisterImplementation(typeof(IShoppingCartCalculationFactory), typeof(CustomShoppingCartCalculationFactory))]

public class CustomShoppingCartCalculationFactory : IShoppingCartCalculationFactory
{
    // Provides an instance of the customized shopping cart calculator
    public IShoppingCartCalculator GetCalculator(SiteInfoIdentifier siteIdentifier)
    {
        // This sample does not parameterize the calculator based on the current site
        // Use the method's 'siteIdentifier' parameter if you need different calculation logic for each site
        return new ShoppingCartCalculatorCollection(CustomCalculationSteps);
    }

    // Defines a custom pipeline of calculation steps
    private static List<IShoppingCartCalculator> CustomCalculationSteps = 
        new List<IShoppingCartCalculator>
        {
            // The default calculation pipeline
            new UnitPriceCalculator(),
            new CartItemDiscountCalculator(),
            new TotalValuesCalculator(),
            new OrderDiscountsCalculator(),
            new TotalValuesCalculator(),
            new ShippingCalculator(),
            new TaxCalculator(),
            new TotalValuesCalculator(),
            new OtherPaymentsCalculator(),
            new TotalValuesCalculator(),

            // Adds the custom "extra charge" step to the end of the calculation
            new ExtraChargeShoppingCartCalculator()
        };
}

6. Save all changes and Build the custom project.

The registered CustomShoppingCartCalculationFactory class provides an instance of ShoppingCartCalculatorCollection with an extended list of calculation steps. The calculation performs all of the default steps without any changes, and the custom ExtraChargeShoppingCartCalculator step at the end of the calculation pipeline adds an extra charge to orders that use the “Custom payment” payment option.