Price calculation

The price calculation service IPriceCalculationService calculates prices, promotions, taxes, shipping costs, and totals across the entire commerce experience – from product catalog displays through shopping cart summaries to final checkout totals.

Different calculation modes optimize the service for each scenario, running only the steps required for that context. This page explains the calculation pipeline and how to choose the right mode for your use case.

Minimum required implementation

To make the price calculation API usable in your project, you need to implement two components:

Once you've implemented and registered these components, the price calculation service automatically handles the rest of the calculation pipeline, including unit price calculations, catalog promotions, subtotals, order promotions, shipping costs, and final totals.

For complete implementation examples, examine the ProductDataRetriever.cs and DancingGoatTaxPriceCalculationStep.cs files in the Dancing Goat sample project.

Calculation modes

The price calculation service supports three calculation modes that determine which steps execute. Set the Mode property on the PriceCalculationRequest to control the calculation scope.

using CMS.Commerce;

// ...

var catalogRequest = new PriceCalculationRequest
{
    Items = productItems,
    LanguageName = "en",
    // Defaults to 'Catalog' if not set
    Mode = PriceCalculationMode.Catalog
};

For detailed usage examples of each mode, see Calculate prices.

Price calculation flow

The price calculation service transforms a PriceCalculationRequest into a PriceCalculationResult through a series of sequential steps:

1. Input preparation – You provide a PriceCalculationRequest containing items to be priced with their product identifiers and quantities. Depending on the calculation mode, you may also include customer details, selected shipping and payment methods, and delivery addresses.

2. Price calculation steps – The IPriceCalculationService executes a series of calculation steps in sequence. Each step performs a specific pricing task, modifying the PriceCalculationResult as it progresses through the pipeline.

3. Result compilation – The service returns a PriceCalculationResult containing itemized pricing details, subtotals, shipping costs, taxes, and the grand total.

Calculation steps

The calculation pipeline consists of the following steps, executed sequentially. Each step only runs if included in the selected calculation mode.

You can customize the default flow by modifying existing steps or adding custom steps to the pipeline.

Calculation walkthrough example

In practice, a Checkout-mode order with two products, an 8% tax rate, and $15.00 flat-rate shipping develops through the steps as follows (tax-exclusive mode, PricesIncludeTax = false):

Input:

• Item A: 2 × $100.00, with a $10.00/unit catalog promotion
• Item B: 1 × $50.00, no catalog promotion
• Order-level promotion: $13.00 off
• No qualifying free shipping promotion – shipping is charged in full

Basic usage

Inject IPriceCalculationService and call Calculate with a PriceCalculationRequest. The service returns a PriceCalculationResult containing itemized prices, totals, and applied promotions.

using System.Linq;
using System.Threading.Tasks;

using CMS.Commerce;

using Microsoft.AspNetCore.Mvc;

public class ShoppingCartController : Controller
{
    private readonly IPriceCalculationService<PriceCalculationRequest, PriceCalculationResult> priceCalculationService;

    public ShoppingCartController(IPriceCalculationService<PriceCalculationRequest, PriceCalculationResult> priceCalculationService)
    {
        this.priceCalculationService = priceCalculationService;
    }

    public async Task<IActionResult> Index(ShoppingCartDataModel shoppingCartData)
    {
        // Build the request with items to price
        var request = new PriceCalculationRequest
        {
            Items = shoppingCartData.Items.Select(item => new PriceCalculationRequestItem
            {
                ProductIdentifier = item.ProductIdentifier,
                Quantity = item.Quantity
            }).ToList(),
            LanguageName = "en",
            Mode = PriceCalculationMode.ShoppingCart
        };

        // Calculates cart prices
        PriceCalculationResult result = await priceCalculationService.Calculate(request);

        // Process the calculation result...
    }
}

For complete examples of each calculation mode, see Calculate prices.

Next steps

• Set up price calculation – Implement product data retrieval and use the calculation service
• Customize price calculation – Extend data objects, modify calculation steps, or add custom steps
• Checkout process – Integrate price calculation into your checkout process