---
title: Price calculation
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

> **License:** Advanced license required.
>
> Features described on this page require the Xperience by Kentico **Advanced** license tier.

The price calculation service `IPriceCalculationService` calculates prices, promotions, taxes, shipping costs, and totals across the entire commerce experience – from [product catalog](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog.md) displays through shopping cart summaries to final [checkout](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/checkout-process.md) 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.

> **Tip:** **Key points**
>
> - The price calculation service uses a **pipeline architecture** with sequential calculation steps.
> - Three **calculation modes** (`Catalog`, `ShoppingCart`, `Checkout`) optimize performance for different scenarios.
> - You must implement a **product data retriever** to connect the service to your catalog. See [Set up price calculation](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md#create-a-product-data-retriever).
> - **Tax calculation** requires a custom implementation – the default step does not calculate taxes. See [Set up price calculation](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md#create-a-tax-calculation-step).
> - All calculation steps can be [customized or extended](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/customization.md) to fit your business logic.

## 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](https://docs.kentico.com/documentation/developers-and-admins/installation.md#available-project-templates) 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.







> **Info:** The default mode is `PriceCalculationMode.Catalog`. Always set the appropriate mode based on your context to ensure correct calculations and optimal performance.

```csharp title="Set calculation mode based on context" highlight="10"
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](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md#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.

![Price calculation flow in Xperience](https://docs.kentico.com/docsassets/documentation/price-calculation/calculation-overview.drawio.svg "Price calculation flow in Xperience")

### Calculation steps

The calculation pipeline consists of the following steps, executed sequentially. Each step only runs if included in the selected [calculation mode](#calculation-modes).

![Calculation steps pipeline](https://docs.kentico.com/docsassets/documentation/price-calculation/calculation-steps-overview.drawio.svg "Calculation steps pipeline")













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](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/catalog-discounts.md)
- Item B: 1 × $50.00, no catalog promotion
- [Order-level promotion](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/order-discounts.md): $13.00 off













> **Info:** **General formula**
>
> **Total = (ΣA − O) × (1 + t) + S**
>
> Where:
>
> - **A** – line subtotal after catalog discount **A = (P - D) x Q**
> - **P** – unit price
> - **D** – catalog discount per unit (fixed amount, or P × discount rate for percentage-based promotions)
> - **Q** – quantity
> - **O** – total order promotion discount
> - **t** – tax rate
> - **S** – shipping cost
>
> When `TaxOptions.PricesIncludeTax` is set to `true`, tax is already included in the unit price – the Tax step extracts it rather than adding it, so the formula becomes **(ΣA − O) + S**. See [Configure tax-inclusive pricing](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md#configure-tax-inclusive-pricing).

You can customize the default flow by [modifying existing steps](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/customization.md#modify-existing-calculation-steps) or [adding custom steps](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/customization.md#add-a-custom-calculation-step) to the pipeline.

## Basic usage

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

```csharp title="Calculate prices for cart items" highlight="10,20-29,32"
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](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md#calculate-prices).

> **Info:** **Multi-currency support**
>
> The price calculation service operates with a single currency by default. If your store requires multi-currency support, you need to implement it as part of your custom solution, for example:
>
> - Store alternate prices in custom fields on your product content type and select the appropriate price in your `IProductDataRetriever` implementation based on the customer's currency preference.
> - Create a custom [calculation step](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/customization.md#add-a-custom-calculation-step) that performs currency conversion using exchange rates from an external service or configuration data.
> - Integrate with a third-party pricing service that handles multi-currency pricing.

## Next steps

- [Set up price calculation](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md) – Implement product data retrieval and use the calculation service
- [Customize price calculation](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/customization.md) – Extend data objects, modify calculation steps, or add custom steps
- [Checkout process](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/checkout-process.md) – Integrate price calculation into your checkout process