Functionality is needed to update the cart once an item has been added. In this guide, you can learn how to add this functionality.

You need a new page to summarize the items in the cart and allow users to update each item.

Create a new Document With a Template. Call it "Cart Page" and update the template with the following code:

@inherits UmbracoViewPage
@{
    var store = Model.Value<StoreReadOnly>("store", fallback: Fallback.ToAncestors);
    var currentOrder = CommerceApi.Instance.GetCurrentOrder(store!.Id);
    if (currentOrder == null) return;
}

• You need to access the store to see the relevant data for the current cart/order. The store has a fallback property allowing you to traverse the tree to find the store.

• currentOrder is used to get the current order for the store. If the current order is null then there is nothing to display.

To display the default layout when an order does exist, you need to add some markup or amend it to include the desired functionality. Add the following code to the template:

@using (Html.BeginUmbracoForm("UpdateCart", "CartSurface"))
{
    @foreach (var item in currentOrder.OrderLines.Select((ol, i) => new
    {
        OrderLine = ol,
        Index = i
    }))
    {
        <p>
            @Html.Hidden($"orderLines[{item.Index}].Id", item.OrderLine.Id)
            @item.OrderLine.Name | @Html.TextBox($"orderLines[{item.Index}].Quantity", (int)item.OrderLine.Quantity, new { @type = "number" })
            @Html.Hidden($"orderLines[{item.Index}].ProductReference", item.OrderLine.ProductReference)
            <a href="@Url.SurfaceAction("RemoveFromBasket", "BasketSurface", new { OrderLineId = item.OrderLine.Id })">Remove</a>
        </p>

    }

    <button type="submit">Update Cart</button>

    var success = TempData["SuccessMessage"]?.ToString();

    if (!string.IsNullOrWhiteSpace(success))
    {
        <div class="success">@success</div>
    }
}

You first loop through each item in the cart/order and display the product name and quantity.

A hidden input is added for the order ID, quantity, and product reference. This is so you can update the cart with the new number.

    @Html.Hidden($"orderLines[{item.Index}].OrderId", item.OrderLine.Id)

The line below sets the ID of the order line (or the item in the current cart/order).

    @item.OrderLine.Name @Html.Hidden($"orderLines[{item.Index}].Quantity", (int)item.OrderLine.Quantity, new { @type = "number" })

As well as setting the product name, the line below sets the quantity of the product in the cart/order. Finally, the number is set to a number input type.

    @Html.Hidden($"orderLines[{item.Index}].ProductReference", item.OrderLine.ProductReference)

This is setting the product reference in the cart/order so there is a way to distinguish between products. This is hidden as it does not need to be displayed to the user.

Finally, a button is added to submit the form to update the cart. This will call the UpdateCart action in the CartSurfaceController which will then show a success message to the user.

Adding the Controller

Create a new Controller called CartSurfaceController.cs

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Logging;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.Routing;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Infrastructure.Persistence;
using Umbraco.Cms.Web.Website.Controllers;
using Umbraco.Commerce.Common.Validation;
using Umbraco.Commerce.Core.Api;
using Umbraco.Commerce.Core.Models;
using Umbraco.Commerce.Extensions;
using Umbraco.Extensions;

public class CartSurfaceController : SurfaceController
{
    public CartSurfaceController(IUmbracoContextAccessor umbracoContextAccessor, 
                                 IUmbracoDatabaseFactory databaseFactory, 
                                 ServiceContext services, AppCaches appCaches, 
                                 IProfilingLogger profilingLogger, 
                                 IPublishedUrlProvider publishedUrlProvider, 
                                 IUmbracoCommerceApi commerceApi) 
                                 : base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
    {
        _commerceApi = commerceApi;
    }
}

The following is the equivalent code for having this as a Primary Constructor:

public class CartSurfaceController(IUmbracoContextAccessor umbracoContextAccessor,
                                   IUmbracoDatabaseFactory databaseFactory, 
                                   ServiceContext services, AppCaches appCaches, 
                                   IProfilingLogger profilingLogger, 
                                   IPublishedUrlProvider publishedUrlProvider, 
                                   IUmbracoCommerceApi commerceApi) 
                                   : SurfaceController(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
{
}

The CartDto is a class that passes data to the Controller. This is a class that has a property for the productReference and an array of OrderLineQuantityDto[].

    public class CartDto
    {
        public string ProductReference { get; set; }
        public OrderLineQuantityDto[] OrderLines { get; set; }
    }

    public class OrderLineQuantityDto
    {
        public Guid Id { get; set; }
        public decimal Quantity { get; set; }
    }

You need to add the Action to update the items in the cart. This will be called when the button is clicked.

[HttpPost]
        public IActionResult UpdateCart(CartDto cart)
        {
            try
            {
                _commerceApi.Uow.Execute(uow =>
                {
                    var store = CurrentPage?.Value<StoreReadOnly>("store", fallback: Fallback.ToAncestors);

                    if (store == null) return;

                    var order = _commerceApi.GetCurrentOrder(store.Id)
                    .AsWritable(uow);

                    foreach (var orderLine in cart.OrderLines)
                    {
                        order.WithOrderLine(orderLine.Id)
                        .SetQuantity(orderLine.Quantity);
                    }

                    _commerceApi.SaveOrder(order);

                    uow.Complete();
                });
            }
            catch (ValidationException)
            {
                ModelState.AddModelError(string.Empty, "Failed to update cart");

                return CurrentUmbracoPage();
            }

            TempData["SuccessMessage"] = "Cart updated";

            return RedirectToCurrentUmbracoPage();
        }

• A try-catch block captures any validation errors that may occur when updating items in the cart.

• The store variable is used to access the store to retrieve the store ID.

• order is used to retrieve the current order. In the Commerce API, everything is read-only for performance so you need to make it writable to add the product.

• You loop through all the orderLines(items) in the cart, set the new quantity amount set in the View, and pass it to the CartDto model.

• SaveOrder is called to save the order.

• If there are any validation errors, they are added to ModelState error, and the user is redirected back to the current page.

• TempData stores a message to be displayed to the user if the product has been successfully updated.

If you have followed the Add item to cart article then run the application, add an item to your cart, and navigate to your cart.cshtml page. Enter a new quantity, click the Update Cart button, and the item(s) in your cart will tell you the values have been updated.

Learn how to install Umbraco Commerce into your Umbraco CMS implementation.

You can also find information about how to upgrade and how to install and activate your Umbraco Commerce license.

NuGet Package Installation

Umbraco Commerce is available via NuGet.Org.

To install Umbraco Commerce via NuGet you can run the following command directly in the NuGet Manager Console window:

PM> dotnet add package Umbraco.Commerce

Alternatively, you can also find and install the NuGet package via the NuGet Package Manager in Visual Studio. You will see a number of packages available, however, you will want to install the main Umbraco Commerce package.

For most sites using a single solution, the above will be all you need to install Umbraco Commerce into your project. When you have a more complex solution structure consisting of multiple projects, Umbraco Commerce is available in multiple sub-packages with varying dependencies.

Installing a License

See the Licensing page for details on how to install a license.

Umbraco Commerce is the official Umbraco e-commerce addon for your Umbraco CMS website. It can be used to set up small webshops, while it can also be implemented for big-scale e-commerce solutions spanning multiple countries.

Extend Umbraco Commerce

Quick links

Using These Docs

These docs are aimed at developers who have at least a basic understanding of Umbraco, as well as C# and MVC principals.

If you require assistance you can use our support channels to seek assistance.

This article shows how to manually upgrade Umbraco Commerce to run the latest version. When upgrading Umbraco Commerce, be sure to also consult the version specific upgrade notes to learn about potential breaking changes and common pitfalls.

Get the latest version of Umbraco Commerce

To get the latest version of Umbraco Commerce you can upgrade using:

• NuGet

• Visual Studio

NuGet

• NuGet installs the latest version of the package when you use the dotnet add package Umbraco.Commerce command unless you specify a package version: dotnet add package Umbraco.Commerce --version <VERSION>

• After you have added a package reference to your project by executing the dotnet add package Umbraco.Commerce command in the directory that contains your project file, run dotnet restore to install the package.

Visual Studio

1. Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution... in Visual Studio, to upgrade Umbraco Commerce:

2. Select Umbraco.Commerce.

3. Select the latest version from the Version drop-down and click Install.

4. When the command completes, open the .csproj file to make sure the package reference is updated:

<ItemGroup>
  <PackageReference Include="Umbraco.Commerce" Version="xx.x.x" />
</ItemGroup>

If you are using one or more of the below sub-packages, they also need to be upgraded as well:

Umbraco Commerce v13.1.0-RC introduces two new exciting strategies for shipping calculation. With these new calculation strategies, calculating shipping costs has become ever more flexible allowing you to have fine grained control over your shipping rates.

Key Takeaways

Dynamic Shipping Rates

With the new dynamic shipping rates feature, it is now possible to define range-based shipping rates configurations. This allows you to adjust shipping costs based on the state of your customer's order. No longer are you tied to a single inflexible fixed rate. Want to charge an excess for bulky/heavy items? no problem. Want to offer cheaper rates for small orders? we got you.

With dynamic shipping rates, you are in full control over every aspect of your rates calculation process.

Range / Rate Providers

With dynamic shipping rates, you aren't only tied to the ranges and rate options we provide out of the box. As with much of the Umbraco Commerce API, we've made these fully pluggable to allow you to be able to define your own. With pluggable range/rate providers, you can truly make dynamic shipping rates tailored to your customer's needs.

Realtime Shipping Rates

With the new realtime shipping rates feature, it is now possible to fetch realtime, up to the minute shipping rates directly from your shipping operator. With realtime rates you can be sure that your shipping rates are as accurate as they can be with minimal configuration required.

Shipping Providers

To help you get started, we are releasing three example shipping providers with this release:

All of these providers are fully open-source so you can see exactly how they work, and use them as a starting point for custom integrations.

API Updates

The dynamic and realtime shipping features also required some updates to other areas of the Umbraco Commerce API. Details of these updates can be found below.

Locations / Store Default Location

To allow shipments to have more dynamic calculations, it's now necessary to know where products are shipping from, not only where they are shipping to. The handle this, store entities now have a Locations child configuration area that allows you to define store locations.

We currently only support a store having a single location which is selected on the Store settings screen via the Default Location setting. We'll be looking in the future to support stores having multiple warehouse locations.

Shipping Packing Factories

Another important aspect of shipping calculations is defining packages along with their dimensions and weight. Umbraco Commerce comes with an out-of-the-box package algorithm. However, with products being stackable in many different ways, we've made this pluggable too to allow you to create more specific packaging logic.

Measurements Property Editor / Store Measurement System

With the shipping packing factories, it also becomes necessary to capture the physical dimensions and weight of the individual products. To help with this, Umbraco Commerce now comes with a Measurements property editor to allow you to define all the physical attributes of your products.

We've also made it so that you can configure your prefered measurement system (metric or imperial) via a setting on the Store node. This setting has a new Measurements property editor taking this into account.

C# / Storefront API Updates

There is a fundamental change that arises with the new dynamic and real-time shipping rates. And that is that it's now no longer possible to retrieve a shipping rate from a shipping method, without a reference order. Additionally, many shipping operators offer different products and services. This means that shipping methods are now able to return multiple rate values for a given rate request.

To accommodate this some APIs have been, such as the shipping method CalculatePrices method is being replaced with TryCalculateRates that accepts an order, and can return multiple rates. In addition, we've also updated the SetShippingMethod API on the order to support passing in a ShippingOption to identify which rate option from the shipping operator is being selected.

These changes have also been made to the Storefront API with some older endpoints becoming deprecated, and new ones being created for these new approaches.

To maintain backward compatibility, the old APIs are still present, but these will only work with return fixed-rate shipping method definitions.

Add-on Updates

In addition to the core Umbraco Commerce changes, updates to the following add-on packages will also be made:

• Umbraco.Commerce.Deploy - Supports the store and shipping method updates as well as the new locations model.

• Umbraco.Commerce.Checkout - Adds support for displaying/selecting shipping rates on the front end.

If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.

Release History

This section contains the release notes for Umbraco Commerce 13 including all changes for this version.

• Updated Umbraco.Licenses dependency to fix issue with license resolution in Azure environments.

• Fixed the OrderHasCustomerEmailAddress query specification performing the wrong comparison (essentially inverted).

• Fixed issue where a recalculation of an order with a shipping method that no longer meets it's eligability criteria rolls back the Unit of Work even if the failure can be automatically rectified.

• Added code to retry requests that result in a DBConcurrencyException.

13.1.18 (February 11th 2025)

• Fixed issue with shipping / payment calculators executing for order with zero line items.

• Fixed issue in unit of work causing child units of work to run their own retry policy. Now limited to only the outer unit of work that executes one.

13.1.16 (January 13th 2025)

• Updated Umbraco.Licenses dependency with latest changes.

13.1.15 (January 8th 2025)

• Fixed issue with inconsistent payment validation incorrectly identifying some payments as inconsistent.

13.1.14 (December 12th 2024)

• Added support for test licenses.

Important If you are running on version 13 of Umbraco Commerce it is advised to upgrade to this version as soon as possible. Changes in .NET 8.0.8 cause an error in our EntityCache which have been resolved in this release. With some hosting providers automatically applying .NET patch releases, upgrading should be proritised to avoid any unintentional breakages.

• Check the config for being undefined in order's edit properties dialog.

• Updated pessimistic locking on the payment provider callback endpoints to lock from the start of the request, not when processing the callback.

• Fixed issue where order lines with a zero value would cause a concurrency exception due to the fact their prices aren't frozen but the order recalculation process was attempting to refreeze them.

• Fixed error with realtime shipping rates provider where the rate cache duration was zero.

• Updated MemoryCache usages to fallback to a default implementation if one isn't found in the DI container.

• Added a WithUmbracoBuilder extension for IUmbracoCommerceBuilder to allow access to the Umbraco configuration within an Umbraco Commerce registration.

• Fixed Order.ProductVariantReference mapping to the wrong field in Storefront API.

• Fixed CountryRegionTaxRate.Country mapping to the wrong field in Storefront API.

13.1.0 (February 21st 2024)

• Minor release closing off the RC period.

• Fixed null exceptions when creating shipping methods with empty config.

• Added helper methods to FixedRateShippingCalculationConfig to make it's API closer to the older fixed rate price lookup API.

13.1.0-rc3 (February 15th 2024)

• Fixed missing SQL Server migrations.

• Fixed realtime shipping rates cache not taking shipping country/region changes into account.

• Fixed realtime shipping rates cache not taking store default location changes into account.

• Updated Umbraco.Licenses version dependency to the latest.

• Made WithUmbracoCommerceBuilder extension public to allow accessing the IUmbracoCommerceBuilder instance outside of the AddUmbracoCommerce call.

13.1.0-rc2 (February 8th 2024)

• Fixed RC1 regression where discount/gift card tree icons were broken.

• Fixed RC1 regression where localized translations were broken.

• Fixed issue in dynamic shipping subtotal range provider not taking the current calculation context into account and so was selecting the wrong range.

13.1.0-rc1 (February 6th 2024)

• Adds dynamic shipping rate calculation option.

• Adds real-time shipping rate calculation option via Shipping Providers.

• Adds store locations for shipping calculations.

• Adds store Measurement System setting.

• Adds Measurements property editor for capturing product measurements for shipping calculations.

• Adds shipping package factory concept for calculating packages for shipments.

• Updates the shipping method create-flow to require selecting a shipping provider and a shipping calculation mode.

• Updates API for calculating shipping prices as payment methods can now return multiple rates.

• Updates the order API for setting the shipping method to accept a ShippingOption for shipping methods that can supply multiple rates.

• Updates the order editor to display the selected shipping option.

• Updates the cart editor to allow selecting a shipping option from real-time shipping methods.

• Updates the cart editor to calculate shipping rates/payment fees based on the current in-memory cart state.

• Updates storefront API to incorporate new shipping rates endpoints.

13.0.2 (February 15th 2024)

13.0.1 (February 6th 2024)

• Reset request stream before passing to payment providers.

• Added licensing fallback to use any previously validated license within the last 7 days.

• Updated Umbraco.Licenses version dependency to the latest.

• Made WithUmbracoCommerceBuilder extension public to allow accessing the IUmbracoCommerceBuilder instance outside of the AddUmbracoCommerce call.

• Upgraded to run again Umbraco v13 and .NET 8

• Upgraded all 3rd party dependencies

• Fixed Cross-site scripting (XSS) issue in email/print templates

Legacy release notes

In this section, you will find information about the key steps necessary to get you started with Umbraco Commerce.

It is assumed that you have an Umbraco 12+ website configured, ready to install Umbraco Commerce into.

System Requirements

The minimum requirements for using Umbraco Commerce are as follows:

• Umbraco CMS version 12+

• SQL Server 2015+ Database

  • SQLite is fine for testing, but not recommended for live deployments. See Configuring SQLite support for more details.

Versioning

This is an add-on product to Umbraco CMS. Umbraco Commerce follows the versioning strategy laid out for Umbraco CMS.

Before you can start to use Umbraco Commerce, you need to configure Umbraco to allow access to the relevant sections. The Umbraco Commerce UI is split over three sections within the Umbraco backoffice:

• Settings for managing the different store settings.

• Commerce for managing store-related content (orders, discounts, etc).

• Content for managing the Umbraco Commerce products.

In order to access these sections, you will need to ensure a User account with the relevant permissions to do so. When logged in as Administrator, access to the Settings and Content sections is already granted.

To gain access to the Commerce section additional configuration is needed.

Creating a Commerce User Group

To gain access to the Commerce section, it is advised to create a new User Group called Commerce.

1. Navigate to the User section of the Umbraco backoffice.

2. Open the User Groups page.

3. Create a new User Group called Commerce.

4. Assign the relevant User accounts to that User Group.

5. Allow that User Group access to the Commerce section as a whole.

Creating a custom User Group provides a way of managing Users who have access to the Commerce section, rather than allowing individual Users access.

Learn more about Users and User Groups in the Umbraco CMS Documentation.

Accessing the Commerce Section

Once created and assigned, you should be able to refresh the backoffice and see that we now have access to the new Commerce section.

This page covers specific upgrade documentation for when migrating to major 13 of Umbraco Commerce.

Version Specific Upgrade Notes History

Version 13 contains a number of breaking changes from the previous, Vendr product.

Legacy version specific upgrade notes

This guide provides a step-by-step approach to migrating a default Vendr solution to Umbraco Commerce.

Key changes

Before outlining the exact steps, there are a few key changes to be aware of.

These changes will dictate the steps to take in the process of migrating to Umbraco Commerce.

Project, Package, and Namespace changes

Step 1: Replace dependencies

In this first step, we will be replacing all existing Vendr dependencies with Umbraco Commerce dependencies.

1. Remove any installed Vendr packages (including Payment Providers):

1. Take a backup of any Vendr-specific templates and config files you will want to reuse:

2. Delete the Vendr App_Plugins folder:

1. Install Umbraco.Commerce:

1. Install Umbraco Commerce packages including any payment providers previously removed.

2. Reapply any backed-up config files in their new App_Plugins location.

3. Move any backed-up templates into the ~/Views/UmbracoCommerce/Templates/ folder.

4. Rename any config files with a .json file extension rather than the previous .js.

5. Compile your project against .NET 7.0.

Step 2: Update namespaces and entity names

Step 3: Update the database

In this step, we will cover updating the database for Umbraco Commerce.

1. Backup your database

2. Rename database tables using the following query:

1. Swap Vendr property editors for Umbraco Commerce property editors:

1. Swap the Vendr variants editor for the Umbraco Commerce variants editor in the block list data entry:

1. Swap Vendr price/amount adjustments to Umbraco Commerce price/amount adjustments:

1. Update template paths:

1. Update the migrations log:

1. Update the activity logs:

Step 4: Finalizing the migration

1. Delete any obj/bin folders in your projects to ensure a clean build.

2. Recompile all projects and ensure all dependencies are restored correctly

3. Delete the existing Vendr license files in the umbraco\Licenses folder.

4. Add your new Umbraco.Commerce license key to the appSettings.json file:

1. Update any payment gateways that use a global webhook:

1. Run the project.

It is highly recommended to ensure everything works as expected, before moving on to migrating packages and custom payment providers.

Further Migrations

If you have been using the Vendr Checkout package, you will need to follow some additional steps to migrate this package to Umbraco Commerce. Follow the link below for a complete guide:

Any custom payment providers used with Vendr also need to be migrated to Umbraco Commerce. Follow the link below to find detailed steps on how to perform this migration:

To add an item to the cart, configure Umbraco with a store and add the necessary properties for interaction. Learn more by following the Getting started with Umbraco Commerce: The Backoffice tutorial.

You will need the front end to be set up to allow an item to be added to the cart. This can be done by adding a button to the front end to call the Action to add the item to the cart.

Create a new Document Type with the template. Call it Product Page with the following property aliases: productTitle, productDescription, price, stock.

The following property editors are recommeded to be used for the above:

• productTitle: TextString

• productDescription: TextArea

• price: Umbraco Commerce Price

• stock: Umbraco Commerce Stock

The Product Page template can be implemented as shown below.

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ProductPage>
@{
var store = Model.Value<StoreReadOnly>("store", fallback: Fallback.ToAncestors);
var product = CommerceApi.Instance.GetProduct(store.Id, Model.Key.ToString(), "en-GB");
var price = product.TryCalculatePrice().ResultOrThrow("Unable to calculate product price");
}

The code above does the following:

• You need to access the store to access the relevant properties for your product, such as price. The store has a fallback property allowing you to traverse the tree to find the store.

• You retrieve the product based on the store and a reference for the product. The 'productReference' comes from the Model which is a single product.

• The Product is returned as a ProductSnapshot which is Umbraco Commerce obtaining the page ID and carrying out necessary processes to bring in the data for further processing.

• Finally, you need to calculate the price which is then displayed without VAT. This can also be displayed with VAT.

To display this you need to add some markup or at least amend it to include a button to add an item. Add the following to the same file:

@using (Html.BeginUmbracoForm("AddToCart", "CartSurface"))
{
	@Html.Hidden("productReference", Model.Key.ToString())
	<h1>@Model.Value<string>("productTitle")</h1>
	<h2>@Model.Value<string>("productDescription")</h2>

	<p>Our price excluding VAT <strong>@price.WithoutTax.ToString("C0") </strong></p>

	if (@Model.Value<int>("stock") == 0)
	{
		<p>Sorry, out of stock</p>
	}
	else
	{
		<button type="submit">Add to Basket</button>
	}

}

The hidden field uses the productReference to be passed across to the Controller.

Adding the Controller

For the button to work, you need to implement a controller. An example of this is shown below.

Create a new Controller called CartSurfaceController.cs.

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Logging;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.Routing;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Infrastructure.Persistence;
using Umbraco.Cms.Web.Website.Controllers;
using Umbraco.Commerce.Common.Validation;
using Umbraco.Commerce.Core.Api;
using Umbraco.Commerce.Core.Models;
using Umbraco.Commerce.Extensions;
using Umbraco.Extensions;

public class CartSurfaceController : SurfaceController
{
    public CartSurfaceController(IUmbracoContextAccessor umbracoContextAccessor, 
                                 IUmbracoDatabaseFactory databaseFactory, 
                                 ServiceContext services, AppCaches appCaches,
                                 IProfilingLogger profilingLogger, 
                                 IPublishedUrlProvider publishedUrlProvider, 
                                 IUmbracoCommerceApi commerceApi) 
                                 : base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
    {
        _commerceApi = commerceApi;
    }
}

Below you can see the equivalent code for having this as a Primary Constructor:

public class CartSurfaceController(IUmbracoContextAccessor umbracoContextAccessor, 
                                   IUmbracoDatabaseFactory databaseFactory, 
                                   ServiceContext services, AppCaches appCaches, 
                                   IProfilingLogger profilingLogger, 
                                   IPublishedUrlProvider publishedUrlProvider) 
                                   : SurfaceController(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
{
}

The CartDto class below is used to pass the productReference across to the Controller. This class has only one property for the productReference.

public class CartDto
{
    public string ProductReference { get; set; }
}

We now need to add the Action to add the item to the cart. This action will be called when the button is clicked.

[HttpPost]
public IActionResult AddToBasket(CartDto cart)
{
    commerceApi.Uow.Execute(uow =>
    {
        var store = CurrentPage.Value<StoreReadOnly>("store", fallback: Fallback.ToAncestors);

        if (store == null) return;

        try
        {
            var order = commerceApi.GetOrCreateCurrentOrder(store.Id)
                .AsWritable(uow)
                .AddProduct(cart.ProductReference, 1);

            commerceApi.SaveOrder(order);

            uow.Complete();

            TempData["SuccessFeedback"] = "Product added to cart";
            return RedirectToCurrentUmbracoPage();
        }
        catch (ValidationException ve)
        {
            throw new ValidationException(ve.Errors);
        }
        catch (Exception ex)
        {
            logger.Error(ex, "An error occurred.");
        }
    });
}

The code above does the following:

• The store variable is used to access the store to get the store ID.

• A try-catch block captures any errors that may occur when adding the item to the cart, including any validation errors.

• order is used to retrieve the current order if one exists or create a new order against the store found. In the Commerce API, everything is read-only for performance so you need to make it writable to add the product.

• AddProduct is called and productReference is passed along with the quantity.

• SaveOrder is called to save the order.

• TempData stores a message to be displayed to the user if the product has been added to the cart.

Finally, you need to add the TempData to tell the user that the product has been added to the cart.

Add a partial view to display the message

Create a new partial view called Feedback.cshtml.

@Html.ValidationSummary(true, "", new { @class = "danger" })

@{
	var success = TempData["SuccessFeedback"]?.ToString();

	if (!string.IsNullOrWhiteSpace(success))
	{
		<div class="success">@success</div>
	}
}

You can now run the application, click the button, and see the product added to the cart with a message displayed to the user.

Within Umbraco Commerce we have support for showing analytics reports, including summaries of sales figures. At the same time, Umbraco Commerce also supports orders being placed in multiple currencies. These pose a problem of how to display a succinct sales figure when the orders are placed in multiple currencies. The answer to this is the store's Base Currency.

When you configure a store you need to assign a base currency to it. This currency is there to identify which currency the store should use as its basis for reports and sales figures. This will be used regardless of whatever currency the order was placed in.

When a store has a base currency configured, any order placed will track the price of the order in the customer's chosen currency. It will also track the current exchange rate between that currency and the store's base currency. Whenever a report is run the order total prices will be converted using this exchange rate. This means that they can all be automatically presented in the single base currency of the store.

Currency Exchange Rates

Umbraco Commerce uses an ICurrencyExchangeRateService to retrieve the most up-to-date rate to be able to track the current exchange rate. This is done for each individual order.

Out of the box, Umbraco Commerce comes with a number of available services you can choose to use. Some are free services, whilst others require a paid subscription.

Historic Orders

Umbraco Commerce has a background service that will attempt to ensure that all historic orders without an exchange rate defined get updated. This is done in case the third-party APIs fail and we need a method of cleaning data. It is also done in case the store base currency is ever changed. In this case, we need to re-process all orders again with the newly selected base currency.

The currency exchange rate background task will run once every 24 hours or after 20 seconds after an app pool recycle.

The Umbraco Commerce UI consists of a number of key areas, split over three sections within the Umbraco backoffice:

• Settings for managing the different store settings.

• Commerce for managing store-related content (orders, discounts, etc).

• Content for managing the Umbraco Commerce products.

Settings Section

The Settings section is where the configuration of all Store settings is managed. From here you can manage how the Store works as well as what options will be available within the Store.

The UI for the Settings section consists of a Tree which lists all available Stores and their key areas available for configuration. It also contains a right-hand editor panel. This can either act as an editor interface or as a list view interface for listing items within that given configuration area.

Each Store has 8 key areas of configuration accessible within the Settings section:

• Store: Each Store node contain Store level configuration settings.

• Order Statuses contain the configuration of the different Statuses an order can be in. Think of these as an organizational structure for your Orders.

• Shipping Methods contains the list of Shipping Methods available to a Store.

• Payment Methods contains the list of Payment Methods available to a Store.

• Countries contain the list of Countries the Store is able to trade with.

• Currencies contain the list of accepted Currencies for the Store.

• Taxes contains the list of Tax Classes and their Tax Rates for the Store.

• Email Templates contains the list of Email Templates supported by the Store.

Commerce Section

The Commerce section contains a Tree to access the Stores and their different features, as well as a right-hand panel for managing the items.

Content Section

The Content section is where the Umbraco Commerce product nodes are managed. Managing products with Umbraco Commerce is similar to working with regular content nodes.

Out of the box, Umbraco Commerce only supports SQL Server-based databases as this is the recommended database platform for live environments. To aid testing and rapid prototyping, however, Umbraco Commerce can be configured to use an SQLite database.

Install SQLite dependencies

To add SQLite support, you will need to install the SQLite persistence layer NuGet package for Umbraco Commerce.

Add .AddUmbracoCommerce() below .AddWebsite() in the Program.cs file.

After configuring Umbraco CMS with SQLite, Umbraco Commerce will automatically utilize the same database configuration. If you wish to install Umbraco Commerce into its own SQLite database you can configure its connection string in the appSettings.json like so:

By default, Umbraco Commerce will use the same database as Umbraco to store its data in. As e-commerce and content management have different database needs, it may be beneficial to house the Umbraco Commerce database tables in an alternative database.

To do this, you can configure a Umbraco Commerce-specific connection string in your app settings ConnectionStrings section using the umbracoCommerceDbDSN prefix.

When Umbraco Commerce runs, it will perform all of its migrations and operations against this database instead of the default Umbraco database.

You might need to execute a custom action for each entity in a selection while extending Umbraco Commerce. For example, being able to trigger label printing for a series of orders, or printing physical gift cards for specific gift card entities.

Umbraco Commerce allows extending the different table views, adding in Bulk Actions to the bulk action bar that appears when you select multiple items. Out of the box all list views contain at minimum a Delete bulk action.

Injecting a Bulk Action

Bulk actions are client-side concepts and so additional bulk actions are injected with JavaScript in an AngularJS configuration module.

To create a configuration module you can create a custom folder in the App_Plugins directory and create a JavaScript file to hold your configuration in.

1. Create a custom folder in the App_Plugins directory.

2. Create a JavaScript file with this new folder.

1. Register the file in a package.manifest file within the same folder.

1. Add the following JSON to the package.manifest file:

1. Inject a bulk action inside the umbraco-commerce-bulk-actions-config.js by adding the following:

Once created, the bulk action will be displayed in the bulk actions bar for the configured entities.

Bulk Action Options

Only an itemAction or a bulkAction method can be defined for a bulk action configuration. If both are present, the bulkAction will be used and the itemAction will be ignored. If processing of items can be done individually, it is better to use the itemAction in order to provide user feedback. The bulkAction can only be used where items need to be processed in a single action.

Important Notes

• Most methods apart from itemAction or bulkAction are optional. If methods aren't present, a default implementation will be used. Where the methods trigger, specific functionality such as the configure or getConfirmMessage methods will become disabled.

• The array-based syntax for registering is a bulk action with angular dependencies. Each bulk action is registered as an array, where all dependencies are defined first and then a factory function is defined last which returns the actual bulk action definition.

• Whilst these docs outline how to define a bulk action, you will likely need to register further resources or services that can perform the given bulk operation and include these as a dependency for your action.

Examples

The following section display an example of a bulk action with dialog configuration step:

This will teach you how to delete an item from the cart.

Your view for the cart.cshtml page will be similar to the example below.

The code below allows the Umbraco SurfaceAction to call RemoveFromCart when the link is clicked. It will also pass the OrderLineId.

Adding the Controller

For the button to work, you need to add some functionality via a Controller.

Create a new Controller called CartSurfaceController.cs

The example below is the equivalent code for having this as a Primary Constructor:

The CartDto is a class used to pass data to the Controller. In this instance, it passes over the OrderLineId.

You need to add the Action to delete the item from the cart. This will be called when the button is clicked.

• A try-catch block captures any validation errors that may occur when updating items in the cart.

• The store variable is used to access the store to retrieve the store ID.

• order is used to retrieve the current order. In the Commerce API, everything is read-only for performance so you need to make it writable to add the product.

• SaveOrder is called to save the order.

• If there are any validation errors, they are added to a ModelState error, and the user is redirected back to the current page.

• TempData stores a message to be displayed to the user if the product has been successfully updated.

In this section, we will look at all the key concepts you will need to understand in order to work with Umbraco Commerce. Many of the concepts are based upon how Umbraco functions, although multiple Umbraco Commerce-specific concepts require your attention.

An added side effect of having ReadOnly and Writable entities is that all of an entity's write operations are now performed via methods. This is instead of property setters, enabling to us convert Umbraco Commerce's write API in a fluent API.

Writing fluently

You could perform a write operation as follows:

_uowProvider.Execute(uow =>
{
    // Fetch the currency
    var currency = _currencyService.GetCurrency(currencyId);

    // Convert the currency into it's Writable form
    var writableCurrency = currency.AsWritable(uow);

    // Perform the write operation
    writableCurrency.SetName("New Name");

    // Persist the changes to the database
    _currencyService.SaveCurrency(currency);

    // Close the transaction
    uow.Complete();
});

This could be simplified further by defining these actions fluently, chaining all of the entity methods into a succinct command sequence as follows:

_uowProvider.Execute(uow =>
{
    var currency = _currencyService.GetCurrency(currencyId)
        .AsWritable(uow)
        .SetName("New Name");

    _currencyService.SaveCurrency(currency);

    uow.Complete();
});

Umbraco Commerce provides support for customizing templates for emails, prints, and exports. This allows you to tailor the outputs of your e-commerce solution to meet specific branding or functional requirements.

Accessing the Default Built-in Templates

The default templates for email, print, and export are embedded in Razor Class Libraries (RCLs) in Umbraco Commerce. To customize these templates, you can extract them and use them as a starting point.

Download the custom templates and place them in /Views/Partials/Commerce/Email/.

Creating Custom Templates

Email Templates

To Create a Custom Email Template:

1. Create a Razor view file (.cshtml) in /Views/Partials/Commerce/Email/.

2. Implement the IEmailTemplate interface to make the template available in Umbraco Commerce:

using Umbraco.Commerce.Core.Interfaces;  

public class CustomOrderEmailTemplate : IEmailTemplate  
{  
    public virtual string FileName => "CustomOrderEmail.cshtml";  
}  

1. Register the Template in a Composer:

using Umbraco.Cms.Core.Composing;  
using Umbraco.Cms.Core.DependencyInjection;  

public class CustomTemplateComposer : IComposer  
{  
    public void Compose(IUmbracoBuilder builder)  
    {  
        builder.EmailTemplates().Add<CustomOrderEmailTemplate>();  
    }  
}  

Print and Export Templates

To create Print/Export Templates:

1. Create a Razor view file (.cshtml) under the relevant paths:

/Views/Partials/Commerce/Prints/  
/Views/Partials/Commerce/Exports/  

1. Implement the IPrintTemplate or IExportTemplate interface to make the template available in Umbraco Commerce.

2. Register the template in a Composer similar to the email template process.

Shipping Custom Templates in a Razor Class Library

To distribute custom templates as part of a Razor Class Library (RCL):

1. Create a new Razor Class Library project.

2. Add the template files under appropriate paths, for example, Views/Partials/Commerce/Emails/.

3. Implement interfaces like IEmailTemplate, IPrintTemplate,or IExportTemplate .

4. Use a composer to register your custom templates.

Discounts in Umbraco Commerce are defined using a series of rules and reward builders that let you configure the following:

• When a Discount should apply.

• What the Reward should be for that Discount.

These builders come with a handful of the most common Rules and Rewards that should suit the majority of web stores' needs. When need to create your own Rules or Rewards then these are extendable via a Provider model allowing you to incorporate your own custom logic.

Discount Rules

There are two types of Discount Rules in Umbraco Commerce:

• Order Discount Rules: Determine whether a discount should apply to an Order. Returns a Fulfilled/Unfulfilled status depending on whether the Rule logic has been met.

• Order Line Discount Rules: Determine whether a discount should apply to an Order Line within an Order. Returns a Fulfilled/Unfulfilled status depending on whether the Rule logic has been met. Where the status is Fulfilled, a list of all Order Lines that are fulfilled by this Rule is also returned.

Example: Custom Order Discount Rule Provider

An example of an Order Discount Rule Provider would look something like this:

[DiscountRuleProvider("myCustomOrderRule", "My Custom Order Rule")]
public class MyCustomOrderRuleProvider : OrderDiscountRuleProviderBase<MyCustomOrderRuleProviderSettings>
{
    public override DiscountRuleResult ValidateRule(DiscountRuleContext ctx, MyCustomOrderRuleProviderSettings settings)
    {
        if (/* Some custom logic */)
            return Fulfilled();
        
        return Unfulfilled();
    }
}

public class MyCustomOrderRuleProviderSettings
{
    [DiscountRuleProviderSetting(Key = "priceType",
        Name = "Price Type",
        Description = "The type of price to compare against")]
    public OrderPriceType PriceType { get; set; }

    ...
}

All Order Discount Rule Providers inherit from a base class OrderDiscountRuleProviderBase<TSettings>. TSettings is the type of a Plain Old Class Object (POCO) model class representing the Discount Rule Providers settings.

The class must be decorated with DiscountRuleProviderAttribute which defines the Discount Rule Providers alias and name, and can also specify a description or icon to be displayed in the backoffice. The DiscountRuleProviderAttribute is also responsible for defining a labelView for the Provider.

Rule Providers have a ValidateRule method that accepts a DiscountRuleContext as well as an instance of the Providers TSettings settings model. Inside this you can perform your custom logic, returning a DiscountRuleResult to notify Umbraco Commerce of the Rule outcome.

If the passed-in context (which contains a reference to the Order) meets the Rule's criteria, then a fulfilled DiscountRuleResult can be returned by calling return Fulfilled();. Alternatively, if the Order didn't meet the Rules criteria an unfulfilled DiscountRuleResult can be returned by calling return Unfulfilled();.

Example: Custom Order Line Discount Rule Provider

An example of an Order Line Discount Rule Provider would look something like this:

[DiscountRuleProvider("myCustomOrderLineRule", "My Custom Order Line Rule")]
public class MyCustomOrderLineRuleProvider : OrderLineDiscountRuleProviderBase<MyCustomOrderLineRuleProviderSettings>
{
    public override DiscountRuleResult ValidateRule(DiscountRuleContext ctx, MyCustomOrderLineRuleProviderSettings settings)
    {
        if (/* Some custom logic */)
            return Fulfilled(fulfilledOrderLines);
        
        return Unfulfilled();
    }
}

public class MyCustomOrderLineRuleProviderSettings
{
    [DiscountRuleProviderSetting(Key = "priceType",
        Name = "Price Type",
        Description = "The type of price to compare against")]
    public OrderPriceType PriceType { get; set; }

    ...
}

All Order Line Discount Rule Providers inherit from a base class OrderLineDiscountRuleProviderBase<TSettings> and follows much the same requirements as the Order Discount Rule Provider defined above. Where they differ is in the ValidateRule method implementation and when a fulfilled DiscountRuleResult is returned. In this case, an Order Line Discount Rule returns a collection of Order Lines processed by the Rule that have met the rules criteria. Whether the rules are met, is checked by calling return Fulfilled(fulfilledOrderLines);.

Discount Rewards

Example: Custom Discount Reward Provider

An example of a Discount Reward Provider would look something like this:

[DiscountRewardProvider("myDiscountReward", "My Discount Reward")]
public class MyDiscountRewardProvider : DiscountRewardProviderBase<MyDiscountRewardProviderSettings>
{
    public override DiscountRewardCalculation CalculateReward(DiscountRewardContext ctx, MyDiscountRewardProviderSettings settings)
    {
        var result = new DiscountRewardCalculation();

        // Some custom calculation logic goes here 

        return result;
    }
}

public class MyDiscountRewardProviderSettings
{
    [DiscountRewardProviderSetting(Key = "priceType",
        Name = "Price Type",
        Description = "The price that will be affected by this reward")]
    public OrderPriceType PriceType { get; set; }

    ...
}

All Discount Reward Providers inherit from a base class DiscountRewardProviderBase<TSettings>. TSettings is the Type of a POCO model class representing the Discount Reward Providers settings.

The class must be decorated with DiscountRewardProviderAttribute which defines the Discount Reward Providers alias and name. It can also specify a description or icon to be displayed in the Umbraco Commerce backoffice. The DiscountRewardProviderAttribute is responsible for defining a labelView for the Provider.

Reward Providers have a CalculateReward method that accepts a DiscountRewardContext as well as an instance of the Providers TSettings settings model. Inside this, you can perform your custom calculation logic, returning a DiscountRewardCalculation instance that defines any Reward values to apply to the Order.

// Add a shipping total discount
result.ShippingTotalPriceAdjustments.Add(new DiscountAdjustment(ctx.Discount, price));

// Add a subtotal discount
result.SubtotalPriceAdjustments.Add(new DiscountAdjustment(ctx.Discount, price));

Common Features

Settings Objects

Label Views

Both the DiscountRuleProviderAttribute and the DiscountRewardProviderAttribute allow you to define a labelView for the Provider. It should be the path to an Angular JS view file that will be used to render a label in the Rule/Reward Builder UI. Where no labelView is supplied, one will be looked for by convention at the following location:

~/app_plugins/umbracocommerce/views/discount/{Type}/labelViews/{ProviderAlias}.html

Type is either rules or rewards, depending on the Type of Provider it refers to. ProviderAlias is the alias of the Provider.

The Rule/Reward Label View should provide a user-friendly summary of its settings to display in the relevant Builder UI.

The Label View file will be passed a model property which will be a JavaScript representation of the given Providers settings object.

<span ng-if="model.priceType">Order {{ model.priceType | umbracoCommerceSplitCamelCase }} Discount</span>

In Umbraco Commerce, a Payment Form is a form that is displayed immediately prior to redirecting to the Payment Gateway for payment processing. This is usually displayed on some kind of review page, allowing a final review of the Order before commencing payment.

The role of the Payment Form is to perform two tasks:

• Prepare the Order for the Payment Gateway - This includes initializing the Orders transaction info and assigning the Order with an Order Number. It's also at this time that the Order is assigned to a Member if there is currently a logged-in session. This task may also involve passing information to the Payment Gateway to create a session, which the customer will complete in the next step. This is dependent on the Payment Provider implementation.

• Redirect to the Payment Gateway - The configured Payment Provider will return a Form that contains all the relevant information the Payment Gateway needs. This includes the Forms action attribute is set to post to a page on the Payment Gateways server, starting the payment capture process.

Example Payment Form

An example of displaying a Payment Form would look something like this:

The Payment Form is rendered using a using statement to wrap any additional form elements you wish to add, such as a submit button.

The Calculation Process

When an order asks to be re-calculated, this triggers a calculation pipeline which in turn runs a series of calculation tasks. It then calls a number of extendable calculators in order to work out the orders' different prices. Throughout this process, Umbraco Commerce needs to keep track of all these prices as they change. At the same time, it also needs to ensure that the calculation is transactional in case something goes wrong. To accomplish both of these requirements we use a temporary state object called OrderCalculation to store all the information. Only at the end of the calculation, if everything was successful, we can copy those calculated prices back to the order.

Accessing Price Values

In the different calculation extension points, Umbraco Commerce will often pass you both an Order object and the OrderCalculation object. We pass the order to get you access to any information held on it that you may need for calculations, such as custom properties. This shouldn't be used for accessing any price-related values of the order.

As mentioned above, in order to maintain data integrity during the calculation process, the order itself is not updated until the end. This means that any calculations based on the order entities' price values would be based on the orders' previously calculated price values.

In order to base your calculation on the current calculated price values you should instead access the OrderCalculation object.

The OrderCalculation Object

From the OrderCalculation object you can access the different order prices, including order line calculations. The order line calculations are stored in a dictionary. In this dictionary, the key is the order line's ID, and the value is an OrderLineCalculation object holding the calculated prices.

By using the prices from the OrderCalculation object you can ensure that your calculation is based on the most up-to-date values for the order.

Calculators are small service implementations with the sole responsibility of calculating prices for a given aspect of an Order. There are five main Calculator service interfaces in Umbraco Commerce:

• IShippingCalculator - Responsible for calculating the Shipping Method price/tax rate of a given Shipping Method.

• IPaymentCalculator - Responsible for calculating the Payment Method price/tax rate of a given Payment Method.

• IProductCalculator - Responsible for calculating the Product unit price/tax rate of a given Product.

• IOrderLineCalculator - Responsible for calculating the price/tax rate of a given OrderLine.

• IOrderCalculator - Responsible for calculating the entire Order.

All Calculator services can be replaced with alternative implementations should you wish to change how Umbraco Commerce performs its calculations.

Defining a Custom Calculator Implementation

The individual Calculator interfaces may differ but the process for defining a custom Calculator implementation is the same for all of them. It is possible to create a new class that implements the default system Calculator that you wish to replace. You can then override the relevant calculation methods.

Registering a custom Calculator implementation

Price Freezing in Umbraco Commerce is the ability to freeze prices for products that are added to the shopping cart. Umbraco Commerce takes a snapshot of a product's price once it's added to the shopping card. This is done in order to ensure the price is honored for the life of the shopping cart. This process prevents a customer's shopping cart from suddenly changing in value should a price change occur whilst their cart session is in progress.

A product's price is frozen from the point it is added to the current Order, and only for the current Currency of the Order. Should the Customer change the Currency of their Order, then a new snapshot of the product price will be taken for that Currency.

Controlling Price Freezing

There are times when you may wish to control when a frozen price should expire. This could be if a product was incorrectly priced, or if you have rules on how long an Order-session is allowed to maintain price.

On these occasions, you can force frozen prices to expire by using the IPriceFreezerService and its ThawPrices method.

All frozen prices have an OrderId property and a Key that uniquely identifies them. For product prices, this key consists of a generated token of the following format {StoreId}_{OrderId}_{ProductReference}. In addition, the product prices Currency, and date of the freeze are also tracked. It is important to know these details as we can use all of these attributes to target which prices we wish to thaw.

For example, to thaw all prices for a product with the reference c0296b75-1764-4f62-b59c-7005c2348fdd we could call:

Or to thaw all prices for a given Currency that are greater than 30 days old we could call:

Throughout the following steps, we will migrate custom payment providers used for Umbraco Commerce into Umbraco Commerce.

1. Remove any installed Umbraco Commerce packages

1. Install the Umbraco.Commerce packages for the payment providers.

1. Update any namespace references.

2. Update project framework to net7.0.

The final step in the migration is to update all abstract async methods exposed by the base class. It needs to be updated to accept an additional CancellationToken cancellationToken = default parameter as the final method argument. Your Integrated Development Environment (IDE) should provide feedback on all the methods that have been updated.

Throughout the following steps, we will migrate the Checkout package from Vendr to Umbraco Commerce.

1. Make a backup of any custom templates and Vendr UI configuration files.

2. Make a note of all configuration values on the Vendr.Checkout Checkout node.

3. Delete Vendr.Checkout generated checkout nodes.

   • Checkout

     • Customer Information

     • Shipping Method

     • Payment Method

     • Review Order

     • Process Payment

     • Order Confirmation

4. Delete all Vendr.Checkout generated Document Types.

   • [Vendr Checkout] Page

     • [Vendr Checkout] Checkout Page

     • [Vendr Checkout] Checkout Step Page

5. Delete all Vendr.Checkout generated Data Types.

   • [Vendr Checkout] Step Picker

   • [Vendr Checkout] Theme Color Picker

6. Uninstall the Vendr.Checkout Nuget package:

1. Delete any remaining files and folders in the ~/App_Plugins/VendrCheckout directory.

2. Install the Umbraco.Commerce.Checkout package:

1. Locate the Umbraco Commerce Checkout dashboard in the Settings section

2. Click the "Install" button to reinstall the Checkout components in the previous location.

3. Copy any custom configuration files back into the solution.

4. Copy any custom Views into the ~/Views/UmbracoCommerceCheckout/ folder.

In this section, we will provide a series of How-To Guides, showcasing how to perform specific tasks within Umbraco Commerce.

Available guides

In this guide, we will be looking at Validation events in Umbraco Commerce. These enabled you to limit order line quantity based on:

• The existing stock value of the product, and

• The existing quantity of the product in the cart.

ProductAddValidationHandler

When adding a product to the cart we need to verify that the product is in stock. We also need to verify that the customer does not already have the remaining quantities in the cart.

OrderLineQuantityValidationHandler

When changing the order line quantity on the cart page, we need to ensure that the quantities being changed are in stock.

Register event handlers

Finally, we need to register the Umbraco Commerce event handlers via an IUmbracoCommerceBuilder extension.

Umbraco Commerce is a commercial product. You can run Umbraco Commerce unrestricted locally without the need for a license. Running Umbraco Commerce in the public domain will display a warning banner in the backoffice and will limit the maximum number of orders to 20. To remove these restrictions, you'll need to have a valid license.

How does it work?

Licenses are sold per backoffice domain and will also work on all subdomains. If you have alternative staging/QA environment domains, additional domains can be added to the license on request.

Let's say that you have a license configured for your domain, mysite.com, and you've requested two development domains, devdomain.com and devdomain2.com.

The license will cover the following domains:

• localhost

• *.local

• *.mysite.com

• www.mysite.com

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What does a license cover?

There are a few differences as to what the licenses cover:

• A single license covers the installation of Umbraco Commerce in 1 production backoffice domain, as well as in any requested development domains.

• The production domain includes all subdomains (e.g. *.mysite.com).

• The development domains work with or without the www subdomain.

• The license allows for an unlimited number of orders.

• The license also includes localhost and *.local as a valid domain.

Configuring your license

Add additional domains

Installing your license

Once you have received your license code it needs to be installed on your site.

1. Open the root directory for your project files.

2. Locate and open the appSettings.json file.

3. Add your Umbraco Commerce license key to Umbraco:Licenses:Umbraco.Commerce:

Verify the license installation

You can verify that your license is successfully installed by logging into your project's backoffice and navigating to the settings section. Here you will see a license dashboard which should display the status of your license.

When and how to configure an UmbracoApplicationUrl

If you are running on a single domain for both your frontend and backend environments, it's not necessary to configure a UmbracoApplicationUrl.

If you have different domains for your frontend and backend, then it's advised that you configure an UmbracoApplicationUrl set to your backoffice URL. This helps the licensing engine know which URL should be used for validation checks. Without this configuration setting, the licensing engine will try and work out the domain to validate from the HTTP request object. This can lead to errors when switching between domains.

An UmbracoApplicationUrl can be configured in your appSettings.json file like so:

Configuring UmbracoApplicationUrl on Umbraco Cloud

If you are hosting on Umbraco Cloud you will find the configuration described above won't be reflected in your environment. The reason for this is that Umbraco Cloud sets this value as an environment variable set to the Cloud project domain (<your project>.umbraco.io). This overrides what is set via the appSettings.json file.

There are two options in this case:

• Either the domains for each of your Cloud environments can be added to your license.

• Or, for more control and to ensure this value is set correctly for other reasons, you can apply the configuration via code.

For example, in your Program.cs:

In practice, you will probably want to make this a bit more sophisticated. You can read the value from another configuration key, removing the need to hard-code it and have it set as appropriate in different environments. You can also move this code into a composer or an extension method if you prefer not to clutter up the Program.cs file.

Validating a license without an outgoing Internet connection

Some Umbraco installations will have a highly locked down production environment, with firewall rules that prevent outgoing HTTP requests. This will interfere with the normal process of license validation.

On start-up, and periodically whilst Umbraco is running, the license component used by Umbraco Commerce will make an HTTP POST request to https://license-validation.umbraco.com/api/ValidateLicense.

If it's possible to do so, the firewall rules should be adjusted to allow this request.

If such a change is not feasible, there is another approach you can use.

You will need to have a server, or serverless function, that is running and can make a request to the online license validation service. That needs to run on a daily schedule, making a request and relaying it onto the restricted Umbraco environment.

To set this up, firstly ensure you have a reference to Umbraco.Licenses version 13.1 or higher. If the version of Commerce you are using depends on an earlier version, you can add a direct package reference for Umbraco.Licenses.

Then configure a random string as an authorization key in configuration. This is used as protection to ensure only valid requests are handled. You can also disable the normal regular license checks - as there is no point in these running if they will be blocked:

Your Internet-enabled server should make a request of the following form to the online license validation service:

The response should be relayed exactly via an HTTP request to your restricted Umbraco environment:

A header with a key of X-AUTH-KEY and the value of the authorization key you have configured should be provided.

This will trigger the same processes that occur when the normal scheduled validation completes ensuring your product is considered licensed.

When working with the Umbraco Commerce entities, it's important to know that all entities come in two states, ReadOnly and Writable. By default, all Umbraco Commerce API methods will return entities in their ReadOnly state. This means that when you are accessing Umbraco Commerce entities directly from an API endpoint you are able to read and iterate over its properties. You won't, however, be able to make changes to that entity without first converting it into its Writable state.

Why have ReadOnly and Writable entities?

The reason why we have split entities in this way for a number of reasons, however, the two primary factors are:

• Making APIs fast by default - By returning ReadOnly entities by default we can ensure all API methods are as fast as possible by feeding values directly out of our caching layer. Because the entities can't change it means we don't have to laden the entities with extra change tracking logic, we can feed out the cached values directly and only worry about that logic when the entities become Writable.

• Simplified change tracking - When we convert a ReadOnly entity to its writable state, internally we take a deep clone of that state so that changes can occur within a scoped "sandbox". At the same time, we retain a copy of the original state meaning when it comes time to persist those changes we have two copies of the state we can perform a comparison on, simplifying the whole change tracking process.

Converting a ReadOnly entity into a Writable entity

To convert a ReadOnly entity into its Writable form, we achieve this by calling the entities AsWritable(uow) method, passing in a valid Unit of Work instance to perform the write operations on. Once we have a Writable entity, we can then perform the write operations we desire and persist those changes back to the database.

_uowProvider.Execute(uow =>
{
    // Fetch the currency
    var currency = _currencyService.GetCurrency(currencyId);

    // Convert the currency into it's Writable form
    var writableCurrency = currency.AsWritable(uow);

    // Peform our write operation
    writableCurrency.SetName("New Name");

    // Persist the changes to the database
    _currencyService.SaveCurrency(currency);

    // Close our transaction
    uow.Complete();
});

Providing a search API for developers to be able to search for entities that match given criteria is a bit of a balancing act. You want to provide a flexible API to allow for meaningful results to be returned but at the same time, you don't want to allow every possible search combination as this can lead to performance problems.

The way we have addressed this is by using the Specification pattern.

Specifications

Specifications are a programming design pattern that allows you to encapsulate business rules in blocks that can be chained together to define boolean logic.

What this means is that we can provide a series of specifications for the types of queries we are able to support in a performant way and allow developers to chain these together in whatever combination they require in order to create dynamic filters for entity searches.

Searching

To perform a search using specifications you'll need to use one of the search methods on the given entity service that accepts a Func<IEntityQuerySpecificationFactory, IQuerySpecification<Entity>> parameter. This parameter type might look complex, but its use should be pretty straightforward thanks to the use of delegates.

To use one of the search methods, the implementation will look something like the following:

var results = _orderService.SearchOrders(
    (where) => where
        .FromStore(storeId)
        .And(where.HasOrderNumber(orderNumber).Or(where.ByCustomer(customerEmail))))

The above is an example, but it demonstrates the use of a delegate method that then uses a fluent specifications API to build up a query filter. The query filter itself can be made up of many different individual queries which themselves can be grouped using AND and OR query logic.

Because the API is fluent it is also self-documenting, with Visual Studio intellisense able to guide developers through all the available specifications.

Ordering Results

Alongside the query specifications documented above, we also have to sort specifications that allow a similar fluent API for defining the order in which results are returned. These are passed in a similar way to the search methods as demonstrated below.

var results = _orderService.SearchOrders(
    (where) => where
        .FromStore(storeId)
        .And(where.HasOrderNumber(orderNumber).Or(where.ByCustomer(customerEmail))),
    (orderBy) => orderBy
        .FinalizedDate(Sort.Descending)
        .Then(orderBy.CreateDate(Sort.Descending)))

Product variants are the ability to define variants of a given product. If a product was available in multiple color options, you would create a primary product with product variants for each of the color options.

Out of the box, Umbraco Commerce supports two types of product variant setups.

Child Variants

Child variants are where the product variants are set up as child nodes below the primary product. Generally speaking, this setup is only sustainable for single variant options, where there is only one differing option between the variants.

By using child variants the only thing you need to create is your own variant nodes as you already do in Umbraco.

When a child variant is added Umbraco Commerce checks the primary product node for any properties that can't be found on the variant child node.

This approach is how most of the official Demo store is set up.

Complex Variants

Complex variants are where products vary by multiple possible options, such as by size, color, and fit. Complex variants tend to create a lot of variant products which makes the child variants approach impractical.

For complex variants, Umbraco Commerce comes with a variants property editor which will handle a lot of this complexity for you. You can set up a variant element type to use as your data blueprint for your variant products. This can then be linked to the property editor. The variants property editor will use this as the data structure for your variants. You will be presented with the relevant UI to input the product details.

Product Attributes

To aid with the setup of the complex variants, Umbraco Commerce has the Product Attributes concept which defines the individual options that make up your product variants. This could be colors, sizes, and fits. Each product attribute is made up of a label and as many values as needed.

Product attributes are used by the complex variants property editor allowing you to select the combinations of product variants you wish to create. It will automatically generate the product variant entries for you, ready for product information updating.

Dependency Injection (DI) can be an intimidating subject. DI reduces the number of hard-coded dependencies within a codebase by providing a means to define dependencies independently and have them "injected" dynamically. These dependencies are often exposed as interfaces, rather than concrete types. This enables them to be swapped out or replaced with minimal effort.

The ability to "swap out" dependencies is used in Umbraco Commerce in a number of places to allow developers to provide alternative implementations of specific features. This could be the ability to:

• Swap out the default Product Calculator to change how product prices are calculated.

• Swap out the default Order Number Generator should you wish to provide an alternative order numbering strategy.

Umbraco Commerce makes heavy use of the dependency injection mechanism in Umbraco to manage many of the features. It is important to understand how to work with the registration process.

What follows are examples of common tasks you'll need to be able to perform via the DI container in order to work effectively with Umbraco Commerce. For more detailed documentation, it is highly recommended that you read the Umbraco CMS Dependency Injection and IoC documentation.

Registering Dependencies

Registering dependencies is an important ability to understand as this is used to register Umbraco Commerce event handlers and to extend system pipelines.

To register a dependency you need to do so via the IUmbracoBuilder interface. This is exposed within the main Program.cs file, between the AddComposers() method call and the Build() method call.

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    // Append your dependencies here...
    .Build();

You can also add your registration logic inside an IUmbracoBuilder extension method and then call that within the Program.cs file. This is the recommended approach.

public static class UmbracoBuilderExtensions
{
    public static IUmbracoBuilder AddMyDependencies(this IUmbracoBuilder builder)
    {
        // Register my dependencies here via the builder parameter
        ...

        // Return the builder to continue the chain
        return builder;
    }
}

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .AddMyDependencies()
    .Build();

Registering a dependency is achieved by working with the IUmbracoBuilder API:

public static class UmbracoBuilderExtensions
{
    public static IUmbracoBuilder AddMyDependencies(this IUmbracoBuilder builder)
    {
        // Register a singleton dependency
        builder.Services.AddSingleton<IMySingletonService, MySingletonService>();

        // Register a transient dependency
        builder.Services.AddTransient<IMyTransientService, MyTransientService>();

        // Return the builder to continue the chain
        return builder;
    }
}

Replacing Dependencies

Like it is possible to add new dependencies it is also possible to replace existing dependencies. This could be dependencies such as the different Calculators available in Umbraco Commerce.

Where a feature is replaceable, replacing that dependency is also achieved via the IUmbracoBuilder API:

public static class UmbracoBuilderExtensions
{
    public static IUmbracoBuilder AddMyDependencies(this IUmbracoBuilder builder)
    {
        // Replacing the product calculator implementation
        builder.Services.AddUnique<IProductCalculator, MyProductCalculator>();

        // Replacing the default product adapter
        builder.Services.AddUnique<ProductAdapterBase, MyProductAdapter>();

        // Return the builder to continue the chain
        return builder;
    }
}

Injecting Dependencies

As well as registering dependencies, you will also need to know how to access Umbraco Commerce dependencies from within your Controllers. To do this, we add parameters to our Controllers constructor for the dependencies we require. Then, the IoC container will inject them automatically for us.

using Umbraco.Commerce.Core.Api;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.ViewEngines;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Web.Common.Controllers;

namespace MyProject.Web.Controllers
{
    public class HomeController : RenderController
    {
        private readonly IUmbracoCommerceApi _umbracoCommerceApi;

        public HomeController(IUmbracoCommerceApi umbracoCommerceApi, ILogger<HomeController> logger,
            ICompositeViewEngine compositeViewEngine, IUmbracoContextAccessor umbracoContextAccessor)
            : base(logger, compositeViewEngine, umbracoContextAccessor)
        {
            _umbracoCommerceApi = umbracoCommerceApi;
        }

        public  override IActionResult Index()
        {
            // Work with the _umbracoCommerceApi here

            return CurrentTemplate(CurrentPage);
        }
    }
}

There is little information that Umbraco Commerce needs to know about a product in order for it to do its job. There are, however, times when developers require the ability to store additional information against an Order or Order Line. This could be the billing/shipping address of an Order, or any specific configuration details of a given Product on an Order Line.

To help facilitate this Umbraco Commerce has the concept of a Properties collection on both the Order entity and the Order Line entity respectively. The Properties collection of these entities can be thought of as a general store for additional information required by an implementation, but not strictly required by Umbraco Commerce itself.

Anything you need to remember about an Order / Order Line can be stored in its Properties collection.

Setting Properties

To set a Property on an Order or Order Line, it needs to be in its Writable state. Then it's a case of calling one of the related property setting methods:

// Set a single property
order.SetProperty("propertyAlias", "Property Value");

// Set multiple properties at once
order.SetProperties(new Dictionary<string, string>{
    { "propertyAlias1", "Property Value 1" },
    { "propertyAlias2", "Property Value 2" },
    { "propertyAlias3", "Property Value 3" }
})

// Remove a property
order.RemoveProperty("propertyAlias");

Property values can either be a string, or a Umbraco Commerce PropertyValue which allows you to define a value as being Server Side Only. This means that it won't be returned via non-server APIs or Read Only meaning it can't be updated once set.

// Set a string property
order.SetProperty("propertyAlias", "Property Value");

// Set a PropertyValue property as Read Only
order.SetProperty("propertyAlias", new PropertyValue("Property Value", isReadOnly: true));

System Properties

On occasions where Umbraco Commerce needs to capture some information about an Order or Order Line, it uses the Properties collection to store this information. It's useful to know what these properties are as you should avoid using these system-related property keys.

Order System Properties

Order Line System Properties

Automatic Properties

Umbraco Commerce has a built-in mechanism that can be configured to automatically copy properties from a Product information source to the Order Line automatically. This is done by using the Product Property Aliases field on the Store settings screen.

When a Product is added to the Order containing a comma-separated list of property aliases, the property values are automatically copied to the Order Lines Properties collection.

This is useful for occasions such as rendering out the Order Lines on a Cart page and you have Product information you want to display. By copying it to the Order Lines Properties collection, you have instant access to those properties without the need to re-fetch the original Product entity.

Product Uniqueness Properties

Another use of the Properties collection for an Order Line is that of identifying product "Uniqueness".

Umbraco Commerce uses Product Uniqueness to identify either of the two:

• Whether a Product is added to a Cart should be considered as a Quantity increase on an existing Order Line

• Whether it should be considered as a unique product combination and so should be given an Order Line of its own.

A good example of this is when you have configurable products, such as customizable T-Shirt designs. In this case, each unique configuration should be considered as its own Order Line so that you can manage the specific configurations.

Product uniqueness is configured via the Product Uniqueness Property Aliases field on the Store setting screen.

When set to a comma-separated list of property aliases and a Product is added to an Order, the properties are compared against all pre-existing Order Lines for that Product. Should their values be different, then a unique Order Line will be created for that Product.

Umbraco.Commerce.Core.Events.Validation

Order Payment Events

Country Payment Events

Currency Payment Events

Discount Payment Events

Email Template Payment Events

Export Template Payment Events

Fetch Order Payment Events

Gift Card Events

Location Events

Order Events

Payment Method Events

Print Template Events

Product Attribute Events

Region Events

Shipping Method Events

Stock Events

Store Events

Tax Class Events

Umbraco.Commerce.Core.Events.Validation.Handlers.Country

Umbraco.Commerce.Core.Events.Validation.Handlers.Currency

Umbraco.Commerce.Core.Events.Validation.Handlers.Discount

Umbraco.Commerce.Core.Events.Validation.Handlers.EmailTemplate

Umbraco.Commerce.Core.Events.Validation.Handlers.ExportTemplate

Umbraco.Commerce.Core.Events.Validation.Handlers.GiftCard

Umbraco.Commerce.Core.Events.Validation.Handlers.Location

Umbraco.Commerce.Core.Events.Validation.Handlers.Order

Umbraco.Commerce.Core.Events.Validation.Handlers.OrderLine

Umbraco.Commerce.Core.Events.Validation.Handlers.OrderStatus

Umbraco.Commerce.Core.Events.Validation.Handlers.PaymentMethod

Umbraco.Commerce.Core.Events.Validation.Handlers.PrintTemplate

Umbraco.Commerce.Core.Events.Validation.Handlers.ProductAttribute

Umbraco.Commerce.Core.Events.Validation.Handlers.Region

Umbraco.Commerce.Core.Events.Validation.Handlers.ShippingMethod

Umbraco.Commerce.Core.Events.Validation.Handlers.Store

Umbraco.Commerce.Core.Events.Validation.Handlers.TaxClass