--- title: Commerce architecture --- > 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. Xperience's commerce platform consists of five core areas that work together to support the full commerce lifecycle: ## Product catalog Products are modeled as Xperience [content types](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md), giving you full control over your catalog structure. There is no fixed SKU table – you define the content types, fields, and taxonomies that match your product domain. The following storage strategies are available: - **Content hub** – Store products as [reusable content items](https://docs.kentico.com/documentation/business-users/content-hub.md), ideal for multi-channel scenarios or when products are not directly tied to website pages. - **Website channel** – Store products as [pages](https://docs.kentico.com/documentation/business-users/website-content.md) in a website channel, suitable when products need their own URLs and SEO metadata. See [Product catalog](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog.md) for modeling guidance and [Example - product catalog](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog/example-product-catalog.md) for a complete implementation. ## Price calculation The `IPriceCalculationService` processes pricing through a configurable pipeline of sequential steps. Three [calculation modes](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation.md#calculation-modes) optimize for different scenarios: - **Catalog** – Product listings and detail pages (unit prices and catalog discounts only) - **ShoppingCart** – Cart display (adds cart item discounts, order discounts, free shipping eligibility, taxes, and totals) - **Checkout** – Final calculation (adds shipping costs) Each step in the pipeline can be [replaced, extended, or reordered](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/customization.md) to implement custom pricing logic. See [Price calculation](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation.md) for the conceptual overview and [Set up price calculation](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md) for implementation details. ## Shopping cart and checkout Shopping carts are persisted in the database as `ShoppingCartInfo` objects. The cart content (`ShoppingCartData`) is a free-form string column – you define and serialize your own cart data model. The checkout process is fully developer-implemented. Xperience provides session management services (`ICurrentShoppingCartRetriever`, `ICurrentShoppingCartCreator`, `ICurrentShoppingCartDiscardHandler`) that handle cart identity for anonymous and authenticated users, but the checkout UI, validation, and payment integration are your responsibility. See [Checkout process](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/checkout-process.md) for implementation guidance. ## Order management `IOrderCreationService` orchestrates the complete order creation workflow: 1. Creates or retrieves customer records based on the `BuyerIdentifier` provided in the order data (linked to [members](https://docs.kentico.com/documentation/business-users/members.md) by member ID, by customer ID, or matched by email for anonymous guests) 2. Runs price calculation for final totals 3. Persists order, order items, and address snapshots in a database transaction 4. Sends [notifications](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/configure-order-statuses.md#configure-notifications-for-order-statuses) via [email channels](https://docs.kentico.com/documentation/developers-and-admins/digital-marketing-setup/email-channel-management.md) and the notifications system See [Create orders](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/checkout-process/order-creation.md) for the API reference and [Customize order creation](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/checkout-process/customize-order-creation.md) for mapper interfaces. ## Promotions The promotion engine supports the following discount types: - [Catalog discounts](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/catalog-discounts.md) – Apply to individual products (e.g., 10% off all items in a category) - [Cart item discounts](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/cart-item-discounts.md) – Discount units already in the cart based on the whole cart content (e.g., buy 3 coffees, the cheapest is half price) - [Order discounts](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/order-discounts.md) – Apply to the entire order (e.g., $20 off orders above $100) - [Free shipping](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/free-shipping.md) – Removes the order's shipping cost when the cart qualifies (e.g., free shipping on orders above $50) When multiple catalog or order promotions compete, the system automatically selects the **best discount** for the customer. Cart item discounts compete with catalog discounts on the same units of a cart item, and the customer gets the better one. Free shipping is evaluated after catalog, cart item, and order promotions and does not compete with them. Promotions support automatic application, [coupon code](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/coupon-codes.md) redemption, and [customer eligibility](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions.md#customer-eligibility) targeting. Custom promotion rules are implemented by developers and configured by business users in the **Promotions** application. See [Promotions](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions.md) for the complete promotions framework. ## Data model The commerce data model centers around orders and customers, with connections to the membership and content systems: ![Commerce data model relationships](https://docs.kentico.com/docsassets/documentation/commerce-architecture/commerce-data-model.drawio.svg "Commerce data model relationships") | Object | Description | Key relationships | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OrderInfo` | A completed order with totals, status, and payment/shipping method references | Links to `CustomerInfo`, `OrderStatusInfo`, contains `OrderItemInfo` and `OrderAddressInfo` children | | `CustomerInfo` | Customer record (name, email, phone). Optionally linked to a member account. | Optional `CustomerMemberID` links to `MemberInfo`. Contains `CustomerAddressInfo` children. | | `ShoppingCartInfo` | Active shopping cart with free-form content data. | Optional `ShoppingCartMemberID` links to `MemberInfo` | | `OrderItemInfo` | Line item with snapshotted product name, price, and quantity. | Child of `OrderInfo` | | `OrderAddressInfo` | Billing/shipping address snapshot frozen at order time. | Child of `OrderInfo` | | `PromotionInfo` | Promotion definition with rules, scheduling, customer eligibility, and coupon configuration. | Referenced by `OrderPromotionInfo` when applied to orders | | `OrderPromotionInfo` | Junction record linking an order to all promotions that were applied. Stores the discount amount and, when the promotion discounts only some of the units of an order item, the number of discounted units (`OrderPromotionPartialQuantity`). | `OrderPromotionOrderID` links to `OrderInfo`, `OrderPromotionOrderItemID` links to `OrderItemInfo`, `OrderPromotionPromotionID` links to `PromotionInfo` | | `OrderPromotionTriggerItemInfo` | An order item that triggered a cart item discount, with the triggering quantity. | `OrderPromotionTriggerItemOrderPromotionID` links to `OrderPromotionInfo`, `OrderPromotionTriggerItemOrderItemID` links to `OrderItemInfo` | ## Scope and limitations The commerce module is designed for **content-driven stores** where product information is managed alongside other website content. Be aware of the following design decisions: - **No built-in payment gateway** – You integrate directly with your payment provider's API. - **No default multi-currency support** – Currency handling must be implemented as part of your custom solution. - **No built-in stock management** – Stock tracking is implemented as a [custom module](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog/model-product-stock.md). > **Info:** These limitations are by design – the framework provides extensible foundations rather than opinionated defaults. These additional capabilities can be implemented through the customization points described above. ## Integration with the Xperience platform The commerce module connects to several core Xperience features: - [Content modeling](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md) – Products are content types with reusable field schemas and taxonomies. - [Membership](https://docs.kentico.com/documentation/business-users/members.md) – Customers can be linked to member accounts. Cart identity is managed for both anonymous and authenticated users. - [Email channels](https://docs.kentico.com/documentation/developers-and-admins/digital-marketing-setup/email-channel-management.md) – Order status notifications are sent through email channels using configurable email templates. - [Notifications](https://docs.kentico.com/documentation/developers-and-admins/configuration/notifications.md) – Internal order notifications are delivered to admin users through the notifications system. ## Core extensibility mechanisms The framework exposes three primary patterns for customization: - **Open generic registration** – Core services like `IPriceCalculationService` and `IOrderCreationService` use generic type parameters, allowing you to substitute custom request, result, and data types while preserving the framework's orchestration logic. - **Pipeline step replacement** – The [price calculation pipeline](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation.md) consists of sequential steps. Any step can be replaced, and the entire pipeline can be reordered or extended to accommodate custom pricing logic. - **Mapper interfaces** – The [order creation service](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/checkout-process/order-creation.md) uses mapper interfaces (e.g., `ICustomerInfoMapper`, `IOrderInfoMapper`) that allow you to inject custom data during order creation without replacing the entire service. See [Customize order creation](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/checkout-process/customize-order-creation.md).