--- 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: | Component | Required for | Description | | -------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Product data retriever** | All modes | Implements `IProductDataRetriever` to load product information and pricing data from your [catalog](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog.md). See [Implement product data retrieval](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md#implement-product-data-retrieval). | | **Tax calculation step** | ShoppingCart, Checkout modes | Overrides the default `ITaxPriceCalculationStep` to calculate taxes. The default implementation does not add 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). | 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. | Mode | Use case | Steps executed | | ---------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- | | **Catalog** | Product listings, category pages, product detail pages | Product data loading, catalog promotions, line subtotals | | **ShoppingCart** | Shopping cart display before shipping selection | All Catalog steps plus order promotions, taxes, line totals, order totals | | **Checkout** | Final checkout with shipping | All steps including shipping calculation | > **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") | Step | Modes | Description | | ------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Load product data | All | Loads product information and pricing data using your `IProductDataRetriever` implementation | | Catalog promotions | All | Applies [catalog promotions](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/catalog-discounts.md) to individual products (best discount wins) | | Line subtotals | All | Calculates line subtotals after catalog discounts | | Shipping | Checkout | Determines shipping cost based on the selected shipping method | | Order promotions | ShoppingCart, Checkout | Applies [order promotions](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/order-discounts.md) that discount the entire order | | Free Shipping | ShoppingCart, Checkout | Determines whether the order qualifies for [free shipping](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/free-shipping.md) | | Taxes | ShoppingCart, Checkout | Calculates taxes (requires custom implementation) | | Line totals | ShoppingCart, Checkout | Calculates final line totals including taxes | | Order total | ShoppingCart, Checkout | Sums line subtotals, shipping, and taxes | | Grand total | ShoppingCart, Checkout | Sets the final grand total to be paid | 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. ### 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](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 - No qualifying [free shipping promotion](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/free-shipping.md) – shipping is charged in full | Step | Operation | Item A | Item B | Order | | ------------------ | ------------------------------------------------- | ----------------------------- | -------------------------- | ----------------------------------- | | Load product data | Load unit prices | $100.00 | $50.00 | – | | Catalog promotions | Apply catalog discounts | −$10.00/unit | (none) | – | | Line subtotals | (Price − Catalog Discount) × Qty | ($100 − $10) × 2 = $180.00 | $50 × 1 = $50.00 | – | | Shipping | Calculate shipping cost | – | – | $15.00 | | Order promotions | Distribute $13.00 order discount proportionally | $13 × ($180 / $230) = $10.17 | $13 × ($50 / $230) = $2.83 | – | | Free Shipping | No qualifying promotion – shipping cost unchanged | – | – | – | | Taxes | (Subtotal − Order Discount) × Tax Rate | ($180 − $10.17) × 8% = $13.59 | ($50 − $2.83) × 8% = $3.77 | – | | Line totals | Subtotal − Order Discount + Tax | $169.83 + $13.59 = $183.42 | $47.17 + $3.77 = $50.94 | – | | Order total | Sum of Line Totals + Shipping | – | – | $183.42 + $50.94 + $15.00 = $249.36 | | Grand total | Final order amount | – | – | $249.36 | > **Info:** **General formula** > > **Total = (ΣA − O) × (1 + t) + S × F** > > 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 > - **F** – [free shipping](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/free-shipping.md) factor: **1** if no free shipping promotion is granted (shipping is charged in full), or **0** if the order qualifies for free shipping (shipping cost is removed) > > 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 × F**. See [Configure tax-inclusive pricing](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md#configure-tax-inclusive-pricing). ## 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 priceCalculationService; public ShoppingCartController(IPriceCalculationService priceCalculationService) { this.priceCalculationService = priceCalculationService; } public async Task 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