--- title: Integrating the shopping cart related: - https://docs.kentico.com/13/e-commerce-features/developing-on-line-stores.md - https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products.md --- > 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). > **Info:** This page is part one of the [Implementing a checkout process](https://docs.kentico.com/13/e-commerce-features/developing-on-line-stores/implementing-a-checkout-process.md) series. The first step towards building a robust checkout process is the implementation of a shopping cart where customers can place desired products. To facilitate shopping cart integration, Xperience provides the _IShoppingService_ service (_CMS.Ecommerce_ namespace) used to manage shopping cart interaction and order creation\*.\* ## Managing a shopping cart _ShoppingService_ simplifies the implementation of all basic shopping cart related activities customers need to perform to complete the checkout process. The service manipulates the shopping cart of the current user, and enables you to create an order from all included items. To begin, create a new controller class utilizing _ShoppingService_ and implemet functionality needed to manage the shopping cart: > **Tip:** **Tip**: View the full code of a functional example in the [LearningKit project](https://github.com/Kentico/LearningKit-Mvc) on GitHub. You can also run the LearningKit website by connecting the project to a Xperience database. Follow the instructions in the repository's README file. 1. Open your live site project in Visual Studio. 2. Create a new controller for the shopping cart. In this series, we will use a controller named **CheckoutController** to house all action methods. 3. Initialize an instance of **IShoppingService** in the controller's constructor. ```csharp /// /// Initializes a instances of services required to manage the checkout process. /// public CheckoutController(IShoppingService shoppingService, IPaymentOptionInfoProvider paymentOption, IShippingOptionInfoProvider shippingOption, ISKUInfoProvider skuInfo, IAddressInfoProvider addressInfo, ICountryInfoProvider countryInfo, IStateInfoProvider stateInfo, IPageRetriever pageRetriever, IPageUrlRetriever pageUrlRetriever) { this.shoppingService = shoppingService; this.pageRetriever = pageRetriever; this.pageUrlRetriever = pageUrlRetriever; this.skuInfo = skuInfo; this.paymentOption = paymentOption; this.shippingOption = shippingOption; this.addressInfo = addressInfo; this.countryInfo = countryInfo; this.stateInfo = stateInfo; } ``` > **Tip:** We recommend using a [dependency injection container](https://docs.kentico.com/13/developing-websites/initializing-xperience-services-with-dependency-injection.md) to initialize instances of used API services (e.g. _IShoppingService)._ The _CheckoutController_ needs to process basic actions that [customers](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/customers.md) require, namely: - [Displaying the contents of the shopping cart](#displaying-the-shopping-cart) - [Adding a product to the shopping cart](#adding-a-product-to-the-shopping-cart) - [Updating a product's quantity in the shopping cart](#updating-a-shopping-cart-item) - [Removing a product from the shopping cart](#removing-a-shopping-cart-item) - [Removing all products from the shopping cart](#removing-all-items-from-the-shopping-cart) - [Moving to the next step of the order creation process](#moving-to-the-next-step-of-the-checkout-process) ### Displaying the shopping cart To display a customer's current shopping cart, add an action method that retrieves their cart, fills a view model representation of the cart, and displays it in a related view. To retrieve the shopping cart for the current customer, use the _IShoppingService.GetCurrentShoppingCart_ method: ```csharp /// /// Displays the customer's current shopping cart. /// public ActionResult ShoppingCart() { // Gets the current user's shopping cart ShoppingCartInfo currentCart = shoppingService.GetCurrentShoppingCart(); // Initializes the shopping cart model ShoppingCartViewModel model = new ShoppingCartViewModel(currentCart); // Displays the shopping cart return View(model); } ``` > **Tip:** **Accessing the current shopping cart** > > You can customize how Xperience retrieves the current shopping cart, for example: > > - When the same shopping cart is used across multiple sites running under one Xperience instance > - When an older saved shopping cart overrides the current shopping cart > - What shopping cart information is removed when the shopping cart is retrieved from the database > > See [Retrieving the current shopping cart](https://docs.kentico.com/13/e-commerce-features/customizing-on-line-stores/shopping-cart-related-customizing/retrieving-the-current-shopping-cart.md) to learn more. Create a view model (the example uses a **ShoppingCartViewModel**) to store select properties of the _ShoppingCartInfo_ object that you want to display or otherwise require in a related view. ```csharp public class ShoppingCartViewModel { public IEnumerable CartItems { get; set; } public string CurrencyFormatString { get; set; } public IEnumerable CouponCodes { get; set; } public decimal TotalTax { get; set;} public decimal TotalShipping { get; set; } public decimal GrandTotal { get; set; } public decimal RemainingAmountForFreeShipping { get; set; } public bool IsEmpty { get; set; } /// /// Constructor for the ShoppingCartViewModel. /// /// A shopping cart object. public ShoppingCartViewModel(ShoppingCartInfo cart) { // Creates a collection containing all lines from the given shopping cart CartItems = cart.CartProducts.Select((cartItemInfo) => { return new ShoppingCartItemViewModel() { CartItemUnits = cartItemInfo.CartItemUnits, SKUName = cartItemInfo.SKU.SKUName, TotalPrice = cartItemInfo.TotalPrice, CartItemID = cartItemInfo.CartItemID, SKUID = cartItemInfo.SKUID, SKUImageUrl = string.IsNullOrEmpty(cartItemInfo.SKU.SKUImagePath) ? null : new FileUrl(cartItemInfo.SKU.SKUImagePath, true) .WithSizeConstraint(SizeConstraint.MaxWidthOrHeight(100)) .RelativePath }; }); CurrencyFormatString = cart.Currency.CurrencyFormatString; CouponCodes = cart.CouponCodes.AllAppliedCodes.Select(x => x.Code); TotalTax = cart.TotalTax; TotalShipping = cart.TotalShipping; GrandTotal = cart.GrandTotal; RemainingAmountForFreeShipping = cart.CalculateRemainingAmountForFreeShipping(); IsEmpty = cart.IsEmpty; } } ``` The **ShoppingCartViewModel** stores the following _ShoppingCartInfo_ properties: - _CartItems_ – A collection of items (products) contained in the shopping cart. > **Note:** Note that each product is itself represented by a _view model_. We strongly recommend creating a separate view model for each database object you want to send to a view template. View models give you full control over the data transferred to and from your views, and can help avoid potential security vulnerabilities. Fill the model only with data you wish to display or otherwise require for the functionality of your view. The **ShoppingCartItemViewModel** contains the following properties: - _SKUName_ – full name of the product as specified during its creation. - _SKUID_ – identifier of the product. - _SKUImageUrl_ – link to the product's image, provided it has one. - _CartItemUnits_ – quantity of the item in the current shopping cart. - _TotalPrice_ – total sum of the item given in the cart's currency. - _CartItemID_ – ID of the given item, used when creating an order from the shopping cart during the final step. ```csharp public class ShoppingCartItemViewModel { public string SKUName { get; set; } public int SKUID { get; set; } public string SKUImageUrl { get; set; } public int CartItemUnits { get; set; } public decimal TotalPrice { get; set; } public int CartItemID { get; set; } } ``` - _CurrencyFormatString_ – a string literal used to format a numeric value based on the shopping cart's selected currency. - _CouponCodes_ – a collection of applied coupon code string literals. See [Working with coupon codes](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts/working-with-coupon-codes.md) for more information about coupon codes in general. > **Tip:** See [Adding coupon code inputs to pages](https://docs.kentico.com/13/e-commerce-features/developing-on-line-stores/implementing-a-checkout-process/integrating-the-shopping-cart/adding-coupon-code-inputs-to-pages.md) to learn more about implementing coupon code support for the shopping cart. - _TotalTax_ – stores the total tax amount that needs to be paid for products currently in the shopping cart. The total tax value is computed from [tax classes](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-taxes.md) assigned to particular products, product variants, and shipping options. - _TotalShipping_ – total shipping to be paid for the products in the current shopping cart. This value is calculated based on the cart's selected [shipping option](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-shipping-options.md). - _GrandTotal_ – total amount to be paid after all taxes, [discounts](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts/working-with-order-discounts.md), and [gift cards](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts/working-with-gift-cards.md) have been applied. - _RemainingAmountForFreeShipping_ – holds the remaining amount required for the order to qualify for any [free shipping offers](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts/working-with-free-shipping-offers.md). - _IsEmpty_ – indicates whether the shopping cart contains any products. In the connected view, use _ShoppingCartViewModel_ to display the shopping cart's contents. For example: ```csharp @if (Model.IsEmpty) { Your shopping cart is empty. } else { @* Allows all items to be removed. *@ @Html.ActionLink("Remove all products", nameof(CheckoutController.RemoveAllItems)) } ``` The excerpt above iterates over all products contained in the shopping cart and displays the name, quantity, and total price of each product. ### Evaluating and saving the shopping cart > **Note:** Methods from the default implementation of the _IShoppingService_ interface handle shopping cart saving and evaluation automatically. When working with objects of the **CMS.Ecommerce.ShoppingCartInfo** type, you may need to manually handle **recalculation** and **saving** of the shopping cart in certain cases (e.g. when extending the default functionality, or implementing a custom variant of the _IShoppingService_ interface). Otherwise your shopping carts may display or store incorrect values. - **ShoppingCartInfo.Evaluate()** – fully recalculates the shopping cart's values and totals based on its current content and properties (discounts, taxes, shipping, etc.). You need to call the _Evaluate_ method after you modify the shopping cart content or set any properties that could affect the calculation results. - **IShoppingService.SaveCart()** – validates and saves the current user's shopping cart object to the database. For example, call this method prior to checkout – the validation may remove items which get sold out before an order is completed. ### Adding a product to the shopping cart Adding a product to the user's current shopping cart can be done via the _IShoppingService.AddItemToCart_ method. The method automatically performs basic validation (valid product, quantity, etc.) on the product, inserts it into the shopping cart, and evaluates the cart. For example, this action can be triggered when a user adds an item to the shopping cart from the [product catalogue](https://docs.kentico.com/13/e-commerce-features/developing-on-line-stores/displaying-product-listings.md) or [product details page](https://docs.kentico.com/13/e-commerce-features/developing-on-line-stores/displaying-product-details.md). ```csharp /// /// Adds products to the customer's current shopping cart. /// /// ID of the added item (its SKU object). /// Quantity of the item to be added. [HttpPost] public ActionResult AddItem(int itemSkuId, int itemUnits) { // Adds the specified number of units of a given product to the current shopping cart shoppingService.AddItemToCart(itemSkuId, itemUnits); // Displays the shopping cart return RedirectToAction("ShoppingCart"); } ``` ### Updating a shopping cart item Update of an item from the user's current shopping cart is facilitated by the _IShoppingService.UpdateItem_ method. The method updates the specified item's quantity and evaluates the cart. This action can be triggered by, for example, a click on an _Update_ button in a view displaying the shopping cart's contents. ```csharp /// /// Updates the quantity of an item in the customer's current shopping cart. /// /// ID of the shopping cart item to update. /// Desired quantity of the shopping cart item being updated. [HttpPost] public ActionResult UpdateItem(int itemID, int itemUnits) { // Updates the quantity of a given product with the specified number of units // If the quantity is set to zero, removes the product from the shopping cart shoppingService.UpdateItemQuantity(itemID, itemUnits); // Displays the shopping cart return RedirectToAction("ShoppingCart"); } ``` ### Removing a shopping cart item Removal of a an item from the user's current shopping cart is handled by _IShoppingServiceService.RemoveItemFromCart_. When removing a [bundle](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/managing-product-representations/managing-bundles.md), the method automatically removes all products belonging to the bundle. For example, you can provide this option when displaying an overview of all items in a shopping cart. ```csharp /// /// Removes a shopping cart item from the customer's current shopping cart. /// /// ID of the item to be removed. [HttpPost] public ActionResult RemoveItem(int itemID) { // Removes a specified product from the shopping cart shoppingService.RemoveItemFromCart(itemID); // Displays the shopping cart return RedirectToAction("ShoppingCart"); } ``` ### Removing all items from the shopping cart Behaving similarly to the [example above](#removing-a-shopping-cart-item), _IShoppingService.RemoveAllItemsFromCart_ removes all products from the user's current shopping cart. For example, you can provide this option when displaying an overview of all items in a shopping cart. ```csharp /// /// Removes all products from the customer's current shopping cart. /// public ActionResult RemoveAllItems() { // Removes all products from the current shopping cart shoppingService.RemoveAllItemsFromCart(); // Displays the shopping cart return RedirectToAction(nameof(CheckoutController.ShoppingCart)); } ``` ## Moving to the next step of the checkout process Implement an action enabling users to continue with the checkout process. The shopping cart needs to be validated and saved before continuing to the next step. This ensures the shopping cart's contents are still valid at the time the action is executed (all contained products are available for purchase, there is a sufficient quantity of them in stock, discounts and coupon codes are correctly applied, etc.): ```csharp /// /// Validates the shopping cart and proceeds to the next checkout step. /// [HttpPost] [ActionName("ShoppingCart")] public ActionResult ShoppingCartCheckout() { // Gets the current user's shopping cart ShoppingCartInfo cart = shoppingService.GetCurrentShoppingCart(); // Validates the shopping cart var cartValidator = ShoppingCartInfoProvider.ValidateShoppingCart(cart); // If the validation is successful, redirects to the next step of the checkout process if (!cartValidator.Any()) { // Saves the validated shopping cart before redirecting the checkout step // This prevents loss of data between requests. shoppingService.SaveCart(); return RedirectToAction("DeliveryDetails"); } // If the validation fails, redirects back to the shopping cart return RedirectToAction("ShoppingCart"); } ``` Continue with the checkout process implementation in the next part of this series: [Gathering customer details during checkout](https://docs.kentico.com/13/e-commerce-features/developing-on-line-stores/implementing-a-checkout-process/gathering-customer-details-during-checkout.md).