• Documentation
  InstallationUsing the Kentico interfaceDeveloping websitesConfiguring KenticoManaging usersSecuring websitesDeploying websitesManaging website contentMultilingual websitesMacro expressionsExternal utilitiesIntegrating 3rd party systemsCustom developmentE-commerce featuresOn-line marketing featuresCommunity featuresRunning Kentico on Microsoft AzureUsing Amazon web services with KenticoCertified extensionsReferencesRelease notes - Kentico 11
• Tutorial
  Getting started with KenticoUsing the Kentico interfaceSite development overviewPortal Engine developmentMVC development
• API Examples
  Content managementOn-line marketingE-commerceSocial and CommunityDevelopmentConfiguration

Calculation interfaces and data types

Main calculation logic

The core shopping cart calculation is performed by the registered implementations of the following interfaces:

• IShoppingCartCalculator
• IShoppingCartCalculationFactory – serves an instance of a class implementing IShoppingCartCalculator for each site. Must be implemented to use custom IShoppingCartCalculator implementations.

Implementations of IShoppingCartCalculator must contain the Calculate method. The method provides a CalculatorData parameter with the following properties:

• Request – a CalculationRequest object that contains the data of the processed shopping cart, such as a collection of cart items (products), the customer object, the cart currency, etc.
• Result – a CalculationResult object that stores the results of the calculation, such as shopping cart totals, discount summaries, tax summaries, etc.

To fully replace the shopping cart calculation logic, the Calculate method of your IShoppingCartCalculator implementation needs to process the data provided in CalculatorData.Request and set all available properties of CalculatorData.Result.

The default shopping cart calculation in Kentico uses a composite IShoppingCartCalculator step, consisting of multiple other IShoppingCartCalculator implementations that are executed in a specific order. See the Default calculation pipeline section for details.

Integration with shopping carts

The E-commerce API uses the following interfaces to connect the main calculation logic to shopping cart objects:

• IShoppingCartAdapterService – prepares the data for the IShoppingCartCalculator calculations and applies the results to the shopping cart. Implementations must contain the following methods:

  • GetCalculationRequest, GetCalculationResult – methods that initialize the CalculationRequest and CalculationResult objects for the calculation using the data of a specified shopping cart (ShoppingCartInfo).

  • ApplyCalculationResult – applies the results (CalculationResult) to the specified shopping cart (ShoppingCartInfo) after the calculation.

    You can create and register your own IShoppingCartAdapterService implementation if you need to add custom properties into the calculation data for use within IShoppingCartCalculator classes:

    1. Create custom classes that inherit from CalculationRequest or CalculationResult.
    2. Add properties to the classes according to your requirements.
    3. Define the GetCalculationRequest and GetCalculationResult methods within your IShoppingCartAdapterService implementation and return instances of your derived request or result classes.
    4. If you need to use custom result properties to apply values to the shopping cart, convert the CalculationResult parameter to your derived type within the ApplyCalculationResult method.
• IShoppingCartEvaluator – contains an Evaluate method that encapsulates the entire shopping cart evaluation and calculation logic. The default implementation prepares the calculation data using IShoppingCartAdapterService, runs the calculation using IShoppingCartCalculationFactory, and ensures automatic adding of free products to shopping carts for Buy X Get Y discounts.

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:

   C#

   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.

   C#

   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.

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.