Hide menu Last updated: Oct 12 2015

Calculating orders 

The following calculation services are available to calculate order totals in different levels.

Shipment required for correct calculation

When you create an order (cart, purchase order, or payment plan) through the IOrderRepository, a shipment is created. Order calculators calculate only line items that belong to a shipment. This is a changed behavior from the way it worked with workflow activities. 

Calculate all

The IOrderGroupTotalsCalculator makes calculations for the IOrderGroup, it's IOrderForms, IShipments, and ILineItems.

  • The order group.
  • The order group's order forms.
  • Shipments on the order forms.
  • Line items on the shipments.

The method calls all calculators to calculate the values.

public void GetTotals(IOrderGroup orderGroup, IOrderGroupTotalsCalculator calculator)
{
    var calculatedTotals = calculator.GetTotals(orderGroup);

    Debug.WriteLine("Handling total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, calculatedTotals.HandlingTotal);
    Debug.WriteLine("Shipping total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, calculatedTotals.ShippingTotal);
    Debug.WriteLine("Sub total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, calculatedTotals.SubTotal);
    Debug.WriteLine("Tax total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, calculatedTotals.TaxTotal);
    Debug.WriteLine("Total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, calculatedTotals.Total);

    foreach (var form in orderGroup.Forms)
    {
        var orderFormTotals = calculatedTotals[form];

        Debug.WriteLine("Handling total for order form '{0}': {1}", form.OrderFormId, orderFormTotals.HandlingTotal);
        Debug.WriteLine("Shipping total for order form '{0}': {1}", form.OrderFormId, orderFormTotals.ShippingTotal);
        Debug.WriteLine("Sub total for order form '{0}': {1}", form.OrderFormId, orderFormTotals.SubTotal);
        Debug.WriteLine("Tax total for order form '{0}': {1}", form.OrderFormId, orderFormTotals.TaxTotal);
        Debug.WriteLine("Total for order form '{0}': {1}", form.OrderFormId, orderFormTotals.Total);

        foreach (var shipment in form.Shipments)
        {
            var shipmentTotals = orderFormTotals[shipment];

            Debug.WriteLine("Shipping cost for shipment '{0}': {1}", shipment.ShipmentId, shipmentTotals.ShippingCost);
            Debug.WriteLine("Items total for shipment '{0}': {1}", shipment.ShipmentId, shipmentTotals.ItemsTotal);

            foreach (var item in shipment.LineItems)
            {
                Debug.WriteLine("Extended price for '{0}': {1}", item.Code, shipmentTotals[item]);
            }
        }
    }
}

Line item calculator

The ILineItemCalculator calculates a line item's extended price and discounted price.

  • Extended price. Includes order-level discount amount (which is spread over all line items in the shipment) and the line item discount amount.
  • Discounted price. Only calculates the price with the "line item discount amount," that is, the discount for a specific item.
public void GetExtendedPrice(ILineItem lineItem, ILineItemCalculator lineItemCalculator)
{
    var extendedPrice = lineItemCalculator.GetExtendedPrice(lineItem, Currency.USD);
    Debug.WriteLine("Extended price for '{0}': {1}", lineItem.Code, extendedPrice);
}

public void GetDiscountedPrice(ILineItem lineItem, ILineItemCalculator lineItemCalculator)
{
    var extendedPrice = lineItemCalculator.GetDiscountedPrice(lineItem, Currency.USD);
    Debug.WriteLine("Discounted price for '{0}': {1}", lineItem.Code, extendedPrice);
}

Change the default calculation of extended price

By inheriting from the default implementation of the interface, DefaultLineItemCalculator, you can override the extended price calculation. Just override the CalculateExtendedPrice method.

public class LineItemCalculatorSample : DefaultLineItemCalculator
{
    protected override Money GetExtendedPrice(ILineItem lineItem, Currency currency)
    {
        throw new NotImplementedException();
    }

    protected override Money GetDiscountedPrice(ILineItem lineItem, Currency currency)
    {
        throw new NotImplementedException();
    }
}

Change the validation for extended price

The default implementation validates that the extended price is not negative after the calculation. To change the behavior, override the ValidateExtendedPrice method.

public class LineItemCalculatorSample : DefaultLineItemCalculator
{
    protected override void ValidateExtendedPrice(Money money)
    {
        if (money.Amount <= 0)
        {
            throw new ValidationException("Extended price must be greater than 0");
        }
    }
}
Shipping calculator

The IShippingCalculator calculates the shipping cost of an order, order form, and shipment. It also calculates the total amount of line items in the shipment.

public void GetShippingCost(IOrderGroup orderGroup, IShippingCalculator shipmentCalculator, ICurrentMarket currentMarket)
{
    var shipmentCost = shipmentCalculator.GetShippingCost(orderGroup, currentMarket.GetCurrentMarket(), Currency.USD);
    Debug.WriteLine("Shipping cost for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, shipmentCost);
}

public void GetShippingCost(IOrderForm orderForm, IShippingCalculator shipmentCalculator, ICurrentMarket currentMarket)
{
    var shipmentCost = shipmentCalculator.GetShippingCost(orderForm, currentMarket.GetCurrentMarket(), Currency.USD);
    Debug.WriteLine("Shipping cost for order form '{0}': {1}", orderForm.OrderFormId, shipmentCost);
}

public void GetShippingCost(IShipment shipment, IShippingCalculator shipmentCalculator, ICurrentMarket currentMarket)
{
    var shipmentCost = shipmentCalculator.GetShippingCost(shipment, currentMarket.GetCurrentMarket(), Currency.USD);
    Debug.WriteLine("Shipping cost for shipment '{0}': {1}", shipment.ShipmentId, shipmentCost);
}

public void GetShippingItemsTotal(IShipment shipment, IShippingCalculator shipmentCalculator)
{
    var shippingItemsTotal = shipmentCalculator.GetShippingItemsTotal(shipment, Currency.USD);
    Debug.WriteLine("Shipping items total for '{0}': {1}", shipment.ShipmentId, shippingItemsTotal);
}

Change the default calculation of shipping cost and shipping item total

By inheriting from the default implementation of the interface, DefaultShippingCalculator, you can override the shipping cost calculation. To change that calculation, override one or several of the CalculateShippingCost methods. To change the calculation of shipping items' total, override the CalculateShippingItemsTotal method.

public class ShippingCalculatorSample : DefaultShippingCalculator
{
    private readonly ILineItemCalculator _lineItemCalculator;

    public ShippingCalculatorSample(ILineItemCalculator lineItemCalculator)
        : base(lineItemCalculator)
    {
        _lineItemCalculator = lineItemCalculator;
    }

    protected override Money CalculateShippingCost(IOrderGroup orderGroup, IMarket market, Currency currency)
    {
        //iterate over all order forms in this order group and sum the results.
        var shippingTotal = orderGroup.Forms
            .Sum(form => GetShippingCost(form, market, currency).Amount);

        return new Money(shippingTotal, currency);
    }

    protected override Money CalculateShippingCost(IOrderForm orderForm, IMarket market, Currency currency)
    {
        //iterate over all shipments in this order form and sum the results.
        var result = orderForm.Shipments
            .Sum(shipment => GetShippingCost(shipment, market, currency).Amount - shipment.ShippingDiscountAmount);

        return new Money(result, currency);
    }

    protected override Money CalculateShipmentCost(IShipment shipment, IMarket market, Currency currency)
    {
        //find the shipping method assigned to the shipment
        var shippingMethods = ShippingManager.GetShippingMethods(String.Empty);
        var row = shippingMethods.ShippingMethod.FindByShippingMethodId(shipment.ShippingMethodId);

        //get the instance of the shipping provider.
        var type = Type.GetType(row.ShippingOptionRow.ClassName);
        var provider = (IShippingGateway)Activator.CreateInstance(type, market);

        //get the rate for this shipment
        var message = String.Empty;
        var rate = provider.GetRate(row.ShippingMethodId, shipment as Shipment, ref message);

        //convert result to correct currency and return.
        return rate != null ?
            CurrencyFormatter.ConvertCurrency(rate.Money, currency) :
            new Money(0, currency);
    }

    protected override Money CalculateShippingItemsTotal(IShipment shipment, Currency currency)
    {
        //calculate the total price of all line items
        var result = 0m;
        foreach (var lineItem in shipment.LineItems.Where(x => x.Quantity > 0))
        {
            var extemdedPrice = _lineItemCalculator.GetExtendedPrice(lineItem, currency);
            result += extemdedPrice.Amount;
        }

        return new Money(result, currency);
    }
}

Change the validation

The default implementation validates that the shipment cost is not negative after the calculation. To change the behavior, override the method ValidateShipmentCostForOrderValidateShipmentCostForOrderFormValidateShipmentCostForShipment, or ValidateShippingItemTotal, depending on which validation you should override.

public class ShippingCalculatorSample : DefaultShippingCalculator
{
    private readonly ILineItemCalculator _lineItemCalculator;

    public ShippingCalculatorSample(ILineItemCalculator lineItemCalculator)
        : base(lineItemCalculator)
    {
        _lineItemCalculator = lineItemCalculator;
    }

    protected override void ValidateShipmentCostForOrder(Money money)
    {
        if (money.Amount <= 0)
        {
            throw new ValidationException("Shipment cost must be greater than 0");
        }
    }

    protected override void ValidateShipmentCostForOrderForm(Money money)
    {
        if (money.Amount <= 0)
        {
            throw new ValidationException("Shipment cost must be greater than 0");
        }
    }

    protected override void ValidateShipmentCostForShipment(Money money)
    {
        if (money.Amount <= 0)
        {
            throw new ValidationException("Shipment cost must be greater than 0");
        }
    }

    protected override void ValidateShippingItemTotal(Money money)
    {
        if (money.Amount <= 0)
        {
            throw new ValidationException("Shipping item total must be greater than 0");
        }
    }
}

Tax calculator

The ITaxCalculator calculates the tax cost for the shipment, order, and order form.

public void GetTaxTotal(IOrderGroup orderGroup, ITaxCalculator taxCalculator, ICurrentMarket currentMarket)
{
    var taxTotal = taxCalculator.GetTaxTotal(orderGroup, currentMarket.GetCurrentMarket(), Currency.USD);
    Debug.WriteLine("Tax total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, taxTotal);
}

public void GetTaxTotal(IOrderForm orderForm, ITaxCalculator taxCalculator, ICurrentMarket currentMarket)
{
    var taxTotal = taxCalculator.GetTaxTotal(orderForm, currentMarket.GetCurrentMarket(), Currency.USD);
    Debug.WriteLine("Tax total for order form '{0}': {1}", orderForm.OrderFormId, taxTotal);
}

Change the default calculation of tax total

By inheriting from the default implementation of the interface, DefaultTaxCalculator, you can override the calculation of tax total. Just override one or several of the CalculateTaxTotal methods.

public class TaxCalculatorOverridingDefault : DefaultTaxCalculator
{
    public TaxCalculatorOverridingDefault(IContentRepository contentRepository,
        ReferenceConverter referenceConverter,
        IShippingCalculator shippingCalculator)
        : base(contentRepository, referenceConverter, shippingCalculator)
    {
    }

    //override this to implement custom tax retrieval
    protected override IEnumerable GetTaxValues(string taxCategory, string languageCode, IOrderAddress orderAddress)
    {
        return new[] { new TaxValue() };
    }

    //override this to implement custom tax calculation for a shipment
    protected override decimal CalculateTax(IEnumerable taxes, IShipment shipment, IMarket market, Currency currency)
    {
        return 0;
    }
}

Change the validation

The default implementation validates that the tax is not negative after the calculation. To change the behavior, override the  ValidateTaxTotalForOrder method or the ValidateTaxTotalForOrderForm method, depending on which validation you should override.

public class TaxCalculatorOverridingDefault : DefaultTaxCalculator
{
    public TaxCalculatorOverridingDefault(IContentRepository contentRepository,
        ReferenceConverter referenceConverter,
        IShippingCalculator shippingCalculator)
        : base(contentRepository, referenceConverter, shippingCalculator)
    {
    }

    protected override void ValidateTaxTotalForOrder(Money money)
    {
        if (money.Amount <= 0)
        {
            throw new ValidationException("Shipping item total must be greater than 0");
        }
    }

    protected override void ValidateTaxTotalForOrderForm(Money money)
    {
        if (money.Amount <= 0)
        {
            throw new ValidationException("Shipping item total must be greater than 0");
        }
    }
}

Order form calculator

The IOrderFormCalculator calculates the handling total, sub total, and total for an order form.

public void GetOrderGroupTotals(IOrderForm orderForm, IOrderFormCalculator orderFormCalculator, ICurrentMarket currentMarket)
{
    var handlingTotal = orderFormCalculator.GetHandlingTotal(orderForm, Currency.USD);
    var subTotal = orderFormCalculator.GetSubTotal(orderForm, Currency.USD);
    var total = orderFormCalculator.GetTotal(orderForm, currentMarket.GetCurrentMarket(), Currency.USD);

    Debug.WriteLine("Handling total for order form '{0}': {1}", orderForm.OrderFormId, handlingTotal);
    Debug.WriteLine("Sub total for order form '{0}': {1}", orderForm.OrderFormId, subTotal);
    Debug.WriteLine("Total for order form '{0}': {1}", orderForm.OrderFormId, total);
}

Change the default calculations

By inheriting from the default implementation of the interface, DefaultOrderFormCalculator, you can override the calculations. Just override one or several of the CalculateHandlingTotalCalculateSubtotal, or CalculateTotal methods.

Change the validation

The default implementation validates that the total is not negative after the calculation. To change the behavior, override the ValidateHandlingTotalValidateSubtotal, or ValidateTotal method, depending on which validation you should override.

Order calculator

The IOrderGroupCalculator calculates an order's handling total, sub total, and total.

public void GetOrderGroupTotals(IOrderGroup orderGroup, IOrderGroupCalculator orderGroupCalculator, ICurrentMarket currentMarket)
{
    var handlingTotal = orderGroupCalculator.GetHandlingTotal(orderGroup, Currency.USD);
    var subTotal = orderGroupCalculator.GetSubTotal(orderGroup, Currency.USD);
    var total = orderGroupCalculator.GetTotal(orderGroup, currentMarket.GetCurrentMarket(), Currency.USD);

    Debug.WriteLine("Handling total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, handlingTotal);
    Debug.WriteLine("Sub total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, subTotal);
    Debug.WriteLine("Total for order '{0}': {1}", orderGroup.OrderLink.OrderGroupId, total);
}

Change the default calculations

By inheriting from the default implementation of the interface, DefaultOrderGroupCalculator, you override the calculations. Just override one or several of the CalculateHandlingTotalCalculateSubtotal, or CalculateTotal methods.

Change the validation

The default implementation validates that the total is not negative after the calculation. To change the behavior, override the ValidateHandlingTotalValidateSubtotal, or ValidateTotal method, depending on which validation you should override.

Comments

This is great, finaly I can just register my own implementation instead of changing the workflow project (which makes upgrading a nightmare). When do you guys expect that this feature is not beta anymore? And is the current state good enough to use this in production?

Hi,

We are under intensive development for discount/promotion. When I don't think we have decided the date, I would personally expect after the current work is done, we will remove the beta flag - which can be 3-6 months away.

I believe some customers already use the new promotion engine - and the initial feedback are very positive. Of course, we highly recommend you to try new engine (might be not your promotion system, but as a POC), and report back to us any bugs you found. We'll make sure any critical bugs found get fixed ASAP.

Regards,

/Q

Beta tag was removed as of release 9.19.0 (update 118) on 6 July, 2016. See http://world.episerver.com/blogs/Magnus-Strale/2016/7/new-campaign-and-promotion-system-in-episerver-commerce/.