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 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.

See the for full details.

Legacy version specific upgrade notes

You can find the version specific upgrade notes for versions out of support in the .

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.

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.

public class ProductAddValidationHandler : ValidationEventHandlerBase<ValidateOrderProductAdd>
{
    private readonly IProductService _productService;

    public ProductAddValidationHandler(IProductService productService)
    {
        _productService = productService;
    }

    public override void Validate(ValidateOrderProductAdd evt)
    {
        var order = evt.Order;
        var productReference = evt.ProductReference;

        var stock = _productService.GetProductStock(evt.Order.StoreId, productReference);

        if (stock.HasValue && evt.Quantity > stock.Value)
            evt.Fail($"Only {stock} quantities can be purchased for {productReference}.");
    }
}

OrderLineQuantityValidationHandler

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

public class OrderLineQuantityValidationHandler : ValidationEventHandlerBase<ValidateOrderLineQuantityChange>
{
    private readonly IProductService _productService;

    public OrderLineQuantityValidationHandler(IProductService productService)
    {
        _productService = productService;
    }

    public override void Validate(ValidateOrderLineQuantityChange evt)
    {
        var orderLine = evt.OrderLine;
        var productReference = orderLine.ProductReference;

        var stock = _productService.GetProductStock(evt.Order.StoreId, productReference);

        if (stock.HasValue && evt.Quantity.To > stock.Value)
            evt.Fail($"Only {stock} quantities can be purchased for {productReference}.");
    }
}

Register event handlers

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

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register event handlers
        builder.WithValidationEvent<ValidateOrderProductAdd>()
            .RegisterHandler<ProductAddValidationHandler>();

        builder.WithValidationEvent<ValidateOrderLineQuantityChange>()
            .RegisterHandler<OrderLineQuantityValidationHandler>();

        return builder;
    }
}

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

1. Remove any installed Umbraco Commerce packages

dotnet remove package Umbraco.Commerce.Core

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

dotnet add package Umbraco.Commerce.Core

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.

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.

In this section, we will provide a series of follow-along tutorials on how to implement Umbraco Commerce. These will be aimed at getting you set up and running without going into heavy theoretical details. Once you are familiar with working with Umbraco Commerce, you can use the other sections of the documentation to gain a more in-depth knowledge of the different things you'll have implemented.

Webhooks

Umbraco Commerce makes use of the webhooks feature added in Umbraco v13. See the Webhooks documentation for general webooks configuration.

Events

Umbraco Commerce triggers webhooks for the following events:

• Order Finalized - Triggered when an order is converted from a cart to an actual finalized order. This event is useful for notifying external systems of new orders.

• Order Status Changed - Triggered when the status of an order changes. This event is useful for notifying external systems when an order is ready to ship, or has been canceled.

Fixed rate shipping in Umbraco Commerce allows you to define a single, fixed shipping rate to apply to an order. This is the simplest of all the shipping calculation options, but is also the least flexible.

Configuration

• Go to Settings > Commerce > Stores > {Your Store} > Shipping Methods

• Click Create Shipping Method

• Choose the Basic shipping provider

• Chose the Fixed calculation mode option

• Populate the shipping method name, alias, sku and optional image and tax rate

• Enter a fixed rate for the shipping method

• Configure the countries this shipping method should be allowed in

• Optionally define a country specific fixed rate should you wish to have different rates per country

The Store API endpoints allow fetching supported store details.

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 .

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

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 for details on how to install a license.

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.

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:

A Tax Source identifies which geographic location an Order should use in order to calculate its tax liability. Depending on the country that the web store is operating in and the country, an order is being purchased from/shipping to, this can dictate how your taxes should be calculated.

To aid with this Umbraco Commerce allows the Tax Source of a Store to be configured via the implementation of a Tax Source Factory. The Tax Source Factory is responsible for determining the source of Tax given the billing and shipping country of an Order.

Out of the box, Umbraco Commerce comes with two Tax Source Factory implementations:

• DestinationTaxSourceFactory - (Default) Sets the Tax Source as being the destination country where an Order will be shipped to.

• OriginTaxSourceFactory - Sets the Tax Source as being the origin country where an Order was billed to.

Changing the Tax Source Factory

Tax Source Factories are interface using the AddUnique<ITaxSourceFactory, TReplacementTaxSourceFactory>() method on the Services property where the TReplacementTaxSourceFactory parameter is the type of your replacement Tax Source Factory implementation.

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.

There are places in Umbraco Commerce where you can use Settings Objects to pass configuration to a Provider, such as Discount Rule Providers, Reward Providers, and Payment Providers.

The settings objects have a number of responsibilities.

• Typed Settings Model - The type represents a strongly typed settings model the given Provider accepts. Any stored settings in the database will be deserialized to this type before being passed to the Provider for processing. This provides strongly typed access to the relevant configuration settings.

• UI Scaffold - The settings object defines metadata on its properties via an Attribute implementing UmbracoCommerceSettingAttribute, each Provider type has its own attribute type in case they require additional config, for example DiscountRewardProviderSettingAttribute, DiscountRuleProviderSettingAttribute or PaymentProviderSettingAttribute. The attributes are used to dynamically build the AngularJS-based UI for the given Provider configuration. See the section below for more information on UI Scaffolding.

• JavaScript Settings Model - The settings object also defines the JavaScript settings model passed to the Provider editor UI, using either the settings Property name as the object property key, or using the key property of the Setting Attribute declared on the given Property.

UI Scaffolding

An important element of the Settings object is UI Scaffolding. UI Scaffolding is where Umbraco Commerce reads a series of Settings Attributes defined on your Settings object properties in order to dynamically build a User Interface for that Providers settings.

An example of a Discount Reward Settings Object might look something like this:

Attributes define a property key, name, description to display in the UI as well as an optional view and config option to define the Umbraco property editor to use to edit the given property. If no view is defined, one will attempt to automatically be chosen based on the properties value type.

An example of a generated UI built from these properties would look something like this:

Default Values

To define default values for a settings object, you can assign a value to a property in your model and Umbraco Commerce will automatically fall back to that value if no explicit value is defined.

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

Available guides

The Product API endpoints allow fetching essential product related data such as pricing and stock levels.

The Order endpoints are where you will manage your carts/orders and perform cart management functionality. Some examples are adding items to the cart, or setting up billing and shipping details.

The Shipping Method API endpoints allow fetching supported shipping methods from a store.

The Storefront API is broken down into a number endpoints of grouped by resource type. Select a resource type below to review the available endpoints.

The Currency API endpoints allow fetching supported currencies from a store.

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.

Umbraco Commerce offers three different shipping method configurations for calculating shipping rates, which are:

The fixed rate shipping option allows you to configure a single fixed rate for the whole of an order.

The dynamic rate shipping option allows you to configure a series of ranges from which an order will be checked against. These checks identify a which range the order falls within. For each range a series of rate options can be configured. Options include fixed rate per order, a fixed rate per order item, percentage based rates amongst others.

The realtime rate shipping option allows you to configure a connection to a shipping operator to fetch realtime shipping rate estimates for an order.

Shipping Calculators

Should you wish to take more control over the shipping calculation process you can swap out the whole shipping calculator implementation. See the for more details.

The content endpoints provide additional endpoints to the Umbraco Content Delivery API to help with fetching product related content.

The Payment Method API endpoints allow fetching supported payment methods from a store.

The Country API endpoints allow fetching supported countries and their allowed currencies, payment methods and shipping methods from a store.

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.

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.

• ExchangeRatesApiCurrencyExchangeRateService uses the free exchangeratesapi.io API and is the default option.

• FixerCurrencyExchangeRateService uses the fixer.io API which is a reliable paid option (with a reasonable free plan).

• CurrencyLayerCurrencyExchangeRateService uses the currencylayer.com API which is another reliable paid option (with a reasonable free plan).

If you wish to change the currency exchange rate service used, you can do so via the dependency injection approach. This is used to override the default service configuration. For services that require configuration to be passed in, such as service API keys, you'll need to use the factory-based override as follows:

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyServices(IUmbracoCommerceBuilder builder)
    {
        // Register the fixer tax service with your API key
        builder.Services.AddUnique<ICurrencyExchangeRateService>(new FixerCurrencyExchangeRateService("YOUR_FIXER_API_KEY"));
        
        // Return the builder to continue the chain
        return builder;
    }
}

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.

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();
});

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.

PM> dotnet add package Umbraco.Commerce.Persistence.Sqlite

Once the NuGet package is installed, you need to register SQLite support with Umbraco Commerce via the IUmbracoCommerceBuilder interface.

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

.AddUmbracoCommerce(builder => {
    builder.AddSQLite();
})

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:

{
    ...
    "ConnectionStrings": {
        "umbracoDbDSN": "Data Source=|DataDirectory|/Umbraco.sqlite.db;Cache=Private;Foreign Keys=True;Pooling=True",
        "umbracoDbDSN_ProviderName": "Microsoft.Data.SQLite",
        "umbracoCommerceDbDSN": "Data Source=|DataDirectory|/Umbraco.Commerce.sqlite.db;Mode=ReadWrite;Foreign Keys=True;Pooling=True;Cache=Private",
        "umbracoCommerceDbDSN_ProviderName": "Microsoft.Data.SQLite"
    },
    ...
}

Umbraco Commerce uses Umbraco nodes as its source of information. In order for Umbraco Commerce to gather the information it needs, it requires that a number of properties are defined at different locations. These properties must have specific property aliases.

Properties

Unit of Work

When working with Umbraco Commerce's API it is important that data integrity is maintained should any errors occur. In order to achieve this Umbraco Commerce uses the Unit of Work pattern to effectively create a transaction that wraps around sections of your code ensuring that all Umbraco Commerce write operations that occur within that code block must succeed and be persisted in their entirety, otherwise, none of them should, and the database should rollback to its state prior to when those changes were made.

Creating a Unit of Work

Creating a unit of work will require access to Umbraco Commerce's IUnitOfWorkProvider which can be injected into your Controller directly, or can also be accessed via the UoW property on the IUmbraco CommerceApi helper.

Once you have access to either of these entry points, you can define a Unit of Work as follows

_uowProvider.Execute(uow =>
{
    // Perform your write operations here

    uow.Complete();
});

The anatomy of a Unit of Work is an Execute method call on the IUnitOfWorkProvider instance which accepts a delegate function with a uow argument. Inside the delegate, we perform our tasks and confirm the Unit of Work as complete by calling uow.Complete(). If we fail to call uow.Complete() either due to forgetting to add the uow.Complete() call or due to an exception in our code, then any write operations that occur within that code block will not be persisted in the database.

Unit of Work Best Practice

When using a Unit of Work it is best practice that you should perform all write operations inside a single Unit of Work and not create individual Units of Work per write operation.

_uowProvider.Execute(uow =>
{
    // Create a Country
    var country = Country.Create(uow, storeId, "DK", "Denmark");

    _countryService.Save(country);

    // Create a Currency
    var currency = Currency.Create(uow, storeId, "DKK", "Danish Kroner", "da-DK");

    _currencyService.Save(currency);

    uow.Complete();
});

_uowProvider.Execute(uow =>
{
    // Create a Country
    var country = Country.Create(uow, storeId, "DK", "Denmark");

    _countryService.Save(country);

    uow.Complete();
});

_uowProvider.Execute(uow =>
{
    // Create a Currency
    var currency = Currency.Create(uow, storeId, "DKK", "Danish Kroner", "da-DK");

    _currencyService.Save(currency);

    uow.Complete();
});

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:

@using(await Html.BeginPaymentFormAsync(currentOrder)) {
    <button type="submit">Continue to Payment</button>
}

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

When calculating shipping rates, defining how an order is packaged is necessary. This includes the dimensions/weight of that package as well as the location from which and to which the package will be sent. All of this is the responsibility of the Shipping Package Factory to calculate.

Stacked Shortest Dimension Package Factory

The out-of-the-box Package Factory that ships with Umbraco Commerce is the Stacked Shortest Dimension Package Factory. This factory works by aggregating the physical dimensions of each item in an order by stacking them on their shortest dimension. From there, we get the overall height of the package, with the length and width calculated as the maximum dimension of any order item.

The receiver address of the package is calculated from the order, with the sender address being the address of the default location for a store.

The Stacked Shortest Dimension Package Factory currently only supports returning a single package containing the entire contents of the order.

Limitations

There are some limitations of the Stacked Shortest Dimension Package Factory that you may need to take into account:

• Assumes items can be stacked in any orientation

• Doesn't optimize for spreading items out in a box, only stacking into a single stack.

Custom Package Factory

Given the limitations of the Stacked Shortest Dimension Package Factory, it may become necessary to implement your own packaging algorithm. This can be achieved by implementing your package factory class and swapping out the default one in the DI container.

To implement your own package factory you need to implement the ShippingPackageFactoryBase class and implement the CreatePackages method.

public class MyPackageFactory : ShippingPackageFactoryBase
{
    public MyPackageFactory(UmbracoCommerceContext umbracoCommerce)
        : base(umbracoCommerce)
    { }

    public override IEnumerable<Package> CreatePackages(ShippingMethodReadOnly shippingMethod, OrderReadOnly order)
    {
        // Calculate and return packages
    }
}

From within this method you can use whatever logic you need to create packages and calculate their dimensions.

To replace the default factory, register your factory implementation with the DI container in its place. See the Replacing Dependencies documentation for more details.

builder.Services.AddUnique<IShippingPackageFactory, MyPackageFactory>();

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.

Dynamic rate shipping in Umbraco Commerce allows you to define a series of ranges from which an order will be checked against. These checks find which range a given order falls within which in turn identifies the rates that apply. For each range, a series of rate options can be configured. Examples include a fixed rate per order, a fixed rate per order item, or percentage-based rates. By combining these configurable ranges, and different rating options it allows you to create a more dynamic algorithm than the basic fixed-rate shipping option.

Configuration

• Go to Settings > Commerce > Stores > {Your Store} > Shipping Methods

• Click Create Shipping Method

• Choose the Basic shipping provider

• Chose the Dynamic calculation mode option

• Populate the shipping method name, alias, sku and optional image and tax rate

• Choose the range unit to base the rates upon

• Click Add Range to define each range

• Populate the from and to value of the range

• Populate the rate details from the available rate options, leaving blank any option you don't wish to apply

• Configure the countries in this shipping method should be allowed in

Realtime rate shipping in Umbraco Commerce allows you to define real-time, up-to-the-minute shipping estimates directly from the shipping operators.

Configuring Realtime Rate Shipping

To configure Realtime Rate Shipping, follow these steps:

1. Go to Settings.

2. Open the Commerce folder in the Commerce section.

3. Select your store from the Stores dropdown.

4. Go to Shipping Methods.

1. Click Create Shipping Method.

2. Choose the shipping provider for the shipping operator you wish to use.

1. Choose Realtime in the calculation mode option.

1. Enter the Shipping Method Name, Alias, and SKU.

2. Select the tax class from the Tax Class dropdown list.

3. [Optional] Upload an image.

4. Enter the shipping provider's API credentials required to connect to the shipping operator's API.

1. Select the countries this shipping method should be allowed in.

1. Click Save.

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.

The checkout endpoints provide ways of performing a checkout process against an Order. The Storefront API supports two ways of checking out an order, one using hosted checkout pages, and a more advanced option for inline payment processing.

Hosted

With the hosted checkout flow it is required that before redirecting to the payment gateway a checkout token should be generated. This token is passed to the pay endpoint to ensure that only the given order can be processed in response to the checkout request. The pay endpoint should be launched in a WebView/iframe with this token which will redirect to the given Orders payment gateway for payment capture. To determine the outcome of the payment developers should monitor the WebView/iframes URL. They will be redirected to the same pay endpoint URL with either a /completed, /canceled or /errored suffix.

Inline

With the inline checkout flow, it is left to the implementing developer to perform payment capture. Before a capture can begin, the order should be initialized using the initialize endpoint which prepares the Order for capture. The initialize endpoint will return the settings of the Orders selected payment method, along with details of expected metadata needed by the payment provider. Developers can use this data to perform an inline capture and call the confirm endpoint when the capture is successful, passing back any metadata captured.

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

• Added feature for range based rates calculaton.

• Added feature for up to the minute, shipping operator shipping quotes.

• A number of to accomodate the new shipping features.

• are also neccesarry for this release.

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.

Be sure to checkout the documentation for how to get started with them.

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.

Be sure to read the documentation for details on how to setup your own providers.

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.

Be sure to checkout the documentation for how to get started with them.

Shipping Providers

The secret behind realtime rates is the new API. Shipping Providers define a minimal API to encapsulate communication with shipping operators. As you might expect, these are fully pluggable allowing you to work with any shipper operator you and your customers require.

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.

See the concept documentation for more details.

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.

Occasionally you may need to create a product with multiple sub-products. A good example of this is when buying a computer where you may pick the computer as the main product. You can then choose the different components to make up the computer, such as the hard disk options. The final order line then becomes the composite order line of the selected primary product and all its sub-product options. To achieve this kind of configurable product in Umbraco Commerce, we can use a feature called product bundling.

Creating a Bundle

To create a bundle, we first add the primary product to an order as we normally would. In addition to the product/quantity information, we also provide a unique bundleId to identify that adding this product should create a bundle order line.

Adding Sub Products to a Bundle

With the primary product added as a bundle, we can then add sub-products to that bundle by calling one of the AddProductToBundle order methods.

Order Line Price Calculation

By adding sub-products to a bundle, Umbraco Commerce knows to automatically sum up all the sub-product prices together. It will then add them to the unit price of the primary order line for you. This means that there is nothing extra you need to do in the calculation process.

Displaying Bundles in the Back-Office

As you can imagine, product bundles could get rather large making it a little difficult to display them in the backoffice. Umbraco Commerce bundles order lines together in a collapsible user interface. This gives you a clear view of your orders whilst still being able to drill into the detail of the items purchased.

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

Calculators are interface using the AddUnique<TServiceInterface, TReplacementService>() method on the Services property. The TServiceInterface parameter in this case is the Calculator interface Type you wish to replace and TReplacementService is the Type of your custom Calculator implementation.

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:

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.

When extending the calculation process of Umbraco Commerce, either by custom calculators or custom pipeline tasks it is important to be aware of the OrderCalculation object.

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

public class OrderCalculation
{
    public Dictionary<Guid, OrderLineCalculation> OrderLines { get; }

    public Dictionary<string, Amount> GiftCardAmounts { get; }

    public List<string> FulfilledDiscountCodes { get; }

    public List<FulfilledDiscount> FulfilledDiscounts { get; }

    public TaxRate TaxRate { get; set; }

    public OrderSubtotalPrice SubtotalPrice { get; set; }

    public TaxRate ShippingTaxRate { get; set; }

    public TotalPrice ShippingTotalPrice { get; set; }

    public TaxRate PaymentTaxRate { get; set; }

    public TotalPrice PaymentTotalPrice { get; set; }

    public OrderTotalPrice TotalPrice { get; set; }
}

public class OrderLineCalculation
{
    public Dictionary<Guid, OrderLineCalculation> OrderLines { get; }

    public TaxRate TaxRate { get; set; }

    public OrderLineUnitPrice UnitPrice { get; set; }

    public OrderLineTotalPrice TotalPrice { get; set; }

    public Price RollingSubOrderLinesTotalPrice { get; set; }

    public Price RollingSubOrderLinesTotalDiscountPrice { get; set; }
}

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.

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:

With Umbraco Commerce's dynamic shipping rates feature it is possible to configure different rules for calculating an order's shipping rate. With the Shipping Rate Range Provider and Shipping Rate Provider feature, it is possible to extend these rules with your own logic.

Shipping Rate Range Provider

The role of a Shipping Rate Range Provider is to define a unit from which to calculate shipping rates (ie, weight, subtotal, etc). With this unit it is then able to determine within what range of values a given order falls within. It is also responsible for defining what editor view to use when entering range values in the UI.

System Shipping Rate Ranger Providers

Out of the box Umbraco Commerce ships with the following Shipping Rate Range Providers:

• Subtotal - Determines whether an orders subtotal falls within a given range.

• Weight - Determines whether an orders overall weight falls within a given range.

Custom Shipping Rate Range Providers

Should you wish to define some other unit on which to calculate rates, you can create your own providers by implementing the ShippingRateRangeProvider<TRangeModel> base class.

[ShippingRateRangeProvider("myunit", "My Unit",
    editorView: "/App_Plugins/UmbracoCommerceExt/backoffice/views/myunit.html",
    sortOrder: 30)]
public class MyShippingRateRangeProvider : ShippingRateRangeProvider<decimal?>
{
    public override Attempt<int> TryFindRangeIndex(ShippingRateRangeCalculationContext<decimal?> ctx)
    {
        // Use the ctx.Ranges property to find the index that that ctx.Order falls within
        // return Attempt.Succeed(index);
    }
}

The class should be decorated with the ShippingRateRangeProviderAttribute which defines an alias, name, description, editor view and label view for the provider. It implements a single method TryFindRangeIndex which, given a ShippingRateRangeCalculationContext, should find the index the current order falls within a series of preconfigured ranges. The ShippingRateRangeCalculationContext contains a series of useful properties that you can use to form your calculation.

• Ranges - A list of configured ranges from the UI from which to find the index of the given order.

• Order - The order to use when finding the current range.

• Store - The store the order belongs to.

• Currency - The given currency of the order.

• TaxRate - The tax rate for the shipping method.

• Packages - A list of packages created for this shipment.

• OrderCalculation - The current in progress order calculation, should there be one.

Registering your custom Shipping Rate Range Provider

Shipping Rate Range Providers are automatically added by type so there is no specific registration code you need to implement. By inheriting from the ShippingRateRangeProvider<TRangeModel> base class, Umbraco Commerce will automatically load your implementation and add it to the Shipping Rate Range Providers collection.

Shipping Rate Provider

The role of a Shipping Rate Provider is to provide a specific rate calculation. Each range defined in a dynamic shipping method configuration can contain multiple Shipping Rate Provider configurations. By combining multiple rate provider this allows you to build up more advanced calculation logic. The set of rate providers to use in a given calculation is determined by the index returned from the Shipping Rate Range Provider.

System Shipping Rate Providers

Out of the box Umbraco Commerce ships with the following Shipping Rate Providers:

• PricePerOrder - Defines a fixed price to apply per order.

• PricePerOrderItem - Defines a fixed price multiplied by the total number of items in the order.

• PricePerOrderWeightUnit - Defines a fixed price multiplied by the total order weight.

• OrderSubtotalPercentage - Define a percentage of the order subtotal to apply.

Custom Shipping Rate Providers

Should you wish to define some other rate calculation logic, you can create your own providers by implementing the ShippingRateProvider<TConfigModel> base class.

[ShippingRateProvider("myrate", "My Rate",
    editorView: "/App_Plugins/UmbracoCommerceExt/backoffice/views/myrate.html",
    sortOrder: 30)]
public class MyShippingRateProvider : ShippingRateProvider<int>
{
    public override Attempt<Price> TryGetRate(ShippingRateCalculationContext<int> ctx)
    {
        // Use the context parameter to calculate a rate ammount
        // return Attempt.Succeed(Price.Calculate(amount, ctx.TaxRate, ctx.Currency.Id, ctx.Store.PricesIncludeTax));
    }
}

The class should be decorated with the ShippingRateProviderAttribute which defines an alias, name, description, editor view, and label view for the provider. It implements a single method TryGetRate which, given a ShippingRateCalculationContext, should calculate the relevant rate. The ShippingRateCalculationContext contains a series of useful properties that you can use to form your calculation.

• Model - The value for this rate provider captured from the UI.

• Order - The order associated with this calculation.

• Store - The store the order belongs to.

• Currency - The given currency of the order.

• TaxRate - The tax rate for the shipping method.

• Packages - A list of packages created for this shipment.

• OrderCalculation - The current in progress order calculation, should there be one.

Registering your custom Shipping Rate Provider

Shipping Rate Providers are automatically added by type so there is no specific registration code you need to implement. By inheriting from the ShippingRateProvider<TConfigModel> base class, Umbraco Commerce will automatically load your implementation and add it to the Shipping Rate Providers collection.

When it comes to configuring and extending Umbraco Commerce, such as by registering your own event handlers, we achieve this with the IUmbracoCommerceBuilder interface that can be accessed via a delegate function passed into the AddUmbracoCommerce() extension method called on the IUmbracoBuilder interface when explicitly registering Umbraco Commerce.

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddUmbracoCommerce(umbracoCommerceBuilder => {
    // Configure Umbraco Commerce here
    })
    .AddDeliveryApi()
    .AddComposers()
    .Build();

Registering Dependencies

The IUmbracoCommerceBuilder interface gives you access to the current IServiceCollection and IConfiguration to allow you to register dependencies like you would with the IUmbracoBuilder interface but its primary use case would be to access Umbraco Commerce's own collection builders, such as for registering validation or notification events, and any other Umbraco Commerce-specific configuration APIs.

...
.AddUmbracoCommerce(umbracoCommerceBuilder => {

    // Register validation events
    umbracoCommerceBuilder.WithValidationEvent<ValidateOrderProductAdd>()
            .RegisterHandler<MyOrderProductAddValidationHandler>();

})
...

As per the Dependency Injection docs, whilst you can register your dependencies directly within this configuration delegate, you may prefer to group your dependencies registration code into an extension method.

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

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

...
.AddUmbracoCommerce(umbracoCommerceBuilder => {

    umbracoCommerceBuilder.AddMyDependencies();

})
...

public static class StoreBuilderExtensions
{
	public static IUmbracoBuilder AddMyStore(this IUmbracoBuilder umbracoBuilder)
	{
		umbracoBuilder.AddUmbracoCommerce(v =>
		{
			...
		});

		return umbracoBuilder;
	}
}

[ComposeBefore(typeof(UmbracoCommerceComposer))]
public class StoreComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddMyStore();
    }
}

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.

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.

If you have followed the article, run the application, add an item to your cart, and navigate to your cart.cshtml page. Clicking the Remove Item button will delete the item in your cart and display a message.

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 .

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.

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.

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

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:

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.

Pipelines allow a series of tasks to be performed in a set sequence. This is done with the input of a given task being the output of the preceding task. It allows a result to be built up as an input is passed through these individual tasks, instead of being calculated in one go.

The Pipelines feature provides an approach to insert additional steps into the process as pipeline tasks can be added or removed from the pipeline sequence.

Where Pipelines is used, it allows an additional point at which developers can interject some custom logic, tweaking how Umbraco Commerce works.

Consider these use-case examples:

• An additional task could be injected into the CalculateOrderPipeline to alter how an Order is calculated.

• A task could be injected into the EmailSendPipeline to add a dynamic attachment to an email.

Example Pipeline task

An example of a Pipeline task would look something like this:

All Pipeline tasks inherit from a base class PipelineTaskWithTypedArgsBase<TPipelineArgs, TModel>. TPipelineArgs is the type of arguments supported by the pipeline and TModel is the pipeline's return model Type. You then need to implement an Execute method that accepts an instance of the argument's type as input and expects a PipelineResult<TModel> as its output. Inside this method, you can perform your custom logic as required. To complete the pipeline task, you can call Ok(TModel) if the task was successful. This will pass in the updated TModel instance to returnæ. Otherwise, you can call Fail() to fail the whole pipeline.

All pipelines occur within a . In case a Pipeline task fails, the whole pipeline will fail and no changes will persist.

Registering a Pipeline task

Pipeline tasks are interface using the appropriate With{PipelineName}Pipeline() builder extension method. This is done to identify the pipeline you want to extend. You can then call the Add<TTask>() method to add your task to the end of that pipeline.

You can also control the order of when Pipeline tasks run, before or after another task, by appending them via the InsertBefore<TTask>() or InsertAfter<TTask>() methods respectively.

In this section, we have summarized the changes to Umbraco Commerce that were released in each version. Each version has a link to the Commerce issue tracker showing a list of issues resolved in the release. We also link to the individual issues themselves from the detail.

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.

13.2.1 (Mar 31st 2025)

• Fixed an issue in the previous migration that increased the monetary column precision #681.

13.2.0 (Mar 3rd 2025)

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

• Fixed custom headers missing from display in carts list #672.

• 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.

13.1.19 (Feb 19th 2025)

• Fixed regression from 13.1.18 where a Unit of Work was not populating the ambient reference when using uow.Create #670.

• Fixed bug in commerce section dashboard showing the wrong order total value + order total count #601.

• Fixed bug in "Placed On Order After / Before" advanced filters UI loosing the selected dates when re-opening modal #515.

• Fixed bug that deleting a country would throw exception #477.

• Fixed bug where deleting a region didn't update Shipping / Payment Method allowed country regions #669.

• Fixed bug where error is thrown if saving a shipping / payment method without an SKU by adding client side required field validation #384.

• Fixed bug with applyToCurrentOrder not applying changes to default currency #278.

• Fixed bug where changing a gift card code alias would cause error for orders using that gift card #149.

• 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.17 (January 28th 2025)

• Fixed issue with stock cache refresher no refreshing due to incorrect cache key #612.

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.

13.1.13 (November 11th 2024)

• Fixed Rounding issue between Umbraco Commerce and Stripe payment gateway #580.

13.1.12 (November 1st 2024)

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.

• Fixed Exception on GetOrCreateCurrentOrder in SessionManager #581.

13.1.11 (October 25th 2024)

• Fixed regressions due to updates from 13.1.6 not getting merged back into main project #576.

• Fixed bug in group discounts provider based on the issue described in #574.

13.1.10 (October 23rd 2024)

• Fixed regression in bug fix for #571 preventing order details being returned from search queries #575.

13.1.9 (October 23rd 2024)

• Fixed regression in EntityCache updates from 13.1.7/13.1.8 failing under load #573.

• Fixed bug in Order search API throwing ORDER BY clause exception #571.

• Fixed bug in Country create dialog failing if Regions exist within another store instance #568.

• Fixed Price Adjustments applied to bundle sub order line not reflected in the bundle unit price #564.

13.1.8 (October 17th 2024)

• Belt and brace updates to EntityCache and added a logger to log if an attempt is made to set a NULL key #565.

13.1.7 (October 10th 2024)

• Fixed issue where the EntityCache fail after the .NET Software Development Kit (SDK) update #565.

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

13.1.6 (July 11th 2024)

• Fixed issue with the Storefront API hosted checkout not rendering form attributes #532.

• Fixed issue with 13.1.5 migration scripts using too new a feature #539.

• Fixed issue with stock synchronizer prematurely looking up a store #536.

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

13.1.5 (July 3rd 2024)

• Added new IRoundingService to allow overriding the default rounding behavior #506.

• Added pessimistic locking to the payment provider callback endpoint to prevent concurrency issues if the endpoint is called too many times at once #533.

• Fixed issue with malformed script tags in the Storefront API hosted checkout pay endpoint #532.

• Fixed percentage discounts not taking the stores rounding method into account during calculation #506.

• 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.

• Updated Order properties to trim whitespace around values to prevent unexpected behavior #528.

• Updated all currency database tables to support 8 decimal places to prevent rounding issues with order quantities above 1000 #506.

13.1.4 (April 23rd 2024)

• Fixed error in SearchOrder when searching with date ranges #496.

13.1.3 (April 8th 2024)

• Fixed properties set in the background from an entity action lost when resaving the entity from the UI after the action (wasn't fully fixed in 13.1.2) #472.

• Fixed orderline properties not showing in orderline summary by default due to regression from strongly typing UI config files in 13.1.0 #494.

• Added support for localhost sub domains in dev license #493.

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

13.1.2 (March 27th 2024)

• Fixed properties set in the background from an entity action lost when resaving the entity from the UI after the action #472.

• Fixed unable to override cart editor view like you can the order editor view #474.

• Fixed regression where launching the shipping method country prices dialog caused JavaScript errors #480.

• Fixed regression with order list configs not deserializing correctly #485.

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

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

• Added better validation error messages when saving locations missing required fields #481.

13.1.1 (March 3rd 2024)

• Fixed regression where custom order/cart editor view stopped working #469.

• Fixed issue with Locations not deleting #470.

• Fixed issue with date range order searches not working correctly #468.

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.

• Fixed error in SafeLazy not taking null into account and so causing errors when an entity cache entry is evicted #466.

• 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)

Read the v13.1.0-RC release post for further background on this release.

• 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)

• Fixed error in SafeLazy not taking null into account and so causing errors when an entity cache entry is evicted #466.

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.

13.0.0 (December 13th 2023)

• 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

You can find the release notes for Vendr in the Change log file on GitHub.

Much like the standard events in .NET, Umbraco Commerce has an events system to notify you when certain things happen within the application. However, Umbraco Commerce differs slightly in the types of events that are fired and how you register your event handlers.

Events in Umbraco Commerce are registered via the IUmbracoCommerceBuilder interface, rather than via static event delegates. This has a number of advantages, such as being able to control the order of when event handlers are fired. It also allows us to inject dependencies into the event handlers making it a much more decoupled approach to eventing.

In Umbraco Commerce, there are two main types of events you can create handlers for. Both are explained in detail below.

Validation events

Validation events are events that fire immediately before a change is about to be made to an entity. These events allow you to inject your own logic to decide whether an action should be possible or not. We already have a number of validation handlers built in to maintain the consistency of your data. Validation events allow you to extend this behavior with your own rules.

A full list of validation events can be found in the List of validation events.

Example: Validation event handler

An example of a Validation event handler would look something like this:

public class MyOrderProductAddValidationHandler : ValidationEventHandlerBase<ValidateOrderProductAdd>
{
    public override void Validate(ValidateOrderProductAdd evt)
    {
        if (evt.ProductReference == "MyProductRef" && evt.Quantity % 10 != 0)
            evt.Fail("This product can only be purchased in increments of 10");
    }
}

All Validation event handlers inherit from a base class ValidationEventHandlerBase<TEvent> where TEvent is the Type of the event the handler is for. They then have a Validate method that accepts an instance of the event type, and inside which you can perform your custom logic. If the event fails the validation logic, you can call evt.Fail("Your message here") to block the related action from happening and have a ValidationException be thrown. This can then be captured in the front end to display a friendly error message.

Registering a Validation event handler

Validation event handlers are registered via the IUmbracoCommerceBuilder interface using the WithValidationEvent<TEvent>() builder extension method. This is done to identify the event you want to handle and then call the RegisterHandler<THandler>() method to register your handler(s) for that event.

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register my event handlers
        builder.WithValidationEvent<ValidateOrderProductAdd>()
            .RegisterHandler<MyOrderProductAddValidationHandler>();

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

You can control the order of when Validation event handlers run, before or after another Validation event handler. This is done by registering them via the RegisterHandlerBefore<THandler>() or RegisterHandlerAfter<THandler>() methods respectively.

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register MyOrderProductAddValidationHandler to execute before the SomeOtherValidationHandler handler
        builder.WithValidationEvent<ValidateOrderProductAdd>()
            .RegisterHandlerBefore<SomeOtherValidationHandler, MyOrderProductAddValidationHandler>();

        // Register MyOrderProductAddValidationHandler to execute after the SomeOtherValidationHandler handler
        builder.WithValidationEvent<ValidateOrderProductAdd>()
            .RegisterHandlerAfter<SomeOtherValidationHandler, MyOrderProductAddValidationHandler>();

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

Notification events

Notification events are events that fire, often immediately before or after an action is executed. It provides you the ability to run custom logic to react to that action occurring. This is useful for scenarios such as sending emails when an Order is finalized or allowing you to synchronize stock updates with an external system.

Notification events won't allow you to change the behavior of how Umbraco Commerce runs. They provide you with an effective means of reacting when changes occur.

A full list of notification events can be found in the List of notification events.

Example: Notification event handler

An example of a Notification event handler would look something like this:

public class MyOrderFinalizedHandler : NotificationEventHandlerBase<OrderFinalizedNotification>
{
    public override void Handle(OrderFinalizedNotification evt)
    {
        // Implement your custom logic here
    }
}

All Notification event handlers inherit from a base class NotificationEventHandlerBase<TEvent> where TEvent is the Type of the event the handler is for. They then have a Handle method that accepts an instance of the event type, and inside which you can perform your custom logic.

Registering a Notification event handler

Notification event handlers are registered via the IUmbracoCommerceBuilder interface using the WithNotificationEvent<TEvent>() builder extension method. This is used to identify the event you want to handle and then call the RegisterHandler<THandler>() method to register your handler(s) for that event.

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register my event handlers
        builder.WithNotificationEvent<OrderFinalizedNotification>()
            .RegisterHandler<MyOrderFinalizedHandler>();

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

You can also control the order of when Notification event handlers run by registering them via the RegisterHandlerBefore<THandler>() or RegisterHandlerAfter<THandler>() methods respectively.

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyEventHandlers(IUmbracoCommerceBuilder builder)
    {
        // Register MyOrderFinalizedHandler to execute before the SomeOtherNotificationHandler handler
        builder.WithNotificationEvent<OrderFinalizedNotification>()
            .RegisterHandlerBefore<SomeOtherNotificationHandler, MyOrderFinalizedHandler>();

        // Register MyOrderFinalizedHandler to execute after the SomeOtherNotificationHandler handler
        builder.WithNotificationEvent<OrderFinalizedNotification>()
            .RegisterHandlerAfter<SomeOtherNotificationHandler, MyOrderFinalizedHandler>();

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

Stores represent a single shop / commercial entity and contain all the settings a configuration specific to that particular store. They are the root entity from which all other Umbraco Commerce entities are connected. They are also able to be linked to content nodes to connect a store to a site.

Store Settings

General settings for a store can be accessed via the UI by clicking on a store node in the Settings > Commerce section.

General

</tr>
<tr>
  <td>Default Location</td>
  <td>Defines the main location of the store and is used by shipping calculators to work out shipping rates.</td>
</tr>
<tr>
  <td>Default Country</td>
  <td>Defines the default country of the store and is used to set the default payment/shipping country of newly created orders.</td>

</tr>
<tr>
  <td>Default Order Status</td>
  <td>Defines the order status to assign newly created orders to.</td>
</tr>
<tr>
  <td>Error Order Status</td>
  <td>Defines the order status to assign orders to when an error occurs during order processing.</td>

</tr>
<tr>
  <td>Measurement System</td>
  <td>Defines whether to use a Metric or Imperial measurement system when capturing product measurement.</td>

</tr>
<tr>
  <td>Prices Include Tax</td>
  <td>Defines whether all prices entered into the system are inclusive or exclusive of tax.</td>
</tr>
<tr>
  <td>Use Cookies</td>
  <td>Defines whether cookies should be used for tracking a customers current order, allowing them to last between browser sessions.</td>
</tr>
<tr>
  <td>Cookie Timeout</td>
  <td>If using cookies, defines the length of time in minutes the cookie should be persisted for.</td>
</tr>

Notification Settings

Order Settings

Product Settings

</tr>

Gift Card Settings

Store Configuration

Further store configuration can be achieved by setting up different categories of configuration that can be accessed as child nodes to the store node.

The available configuration options are:

• Locations - Defines different locations for a store.

• Order Statuses - Defines the order statuses to be used by a store.

• Shipping Methods - Defines the different shipping options available in the store. See Shipping reference documentation for more details.

• Payment Methods - Defines the different payment options available in the store.

• Countries - Defines the different shipping countries supported by the store.

• Currencies - Defines the different currencies accepted by the store.

• Taxes - Defines the different rates supported by the store.

• Templating - Defines the different email, print, and export templates available to the store.

Store Permissions

When editing a store, the permissions app allows you to control who can access the store management interface. The options are:

• User Groups - A set of toggles to allow/deny access to members of a particular user group.

• Users - A set of toggles to allow/deny access to explicit individuals.

In both cases, a positive access control will always override a deny control setting.

Payment Providers are how Umbraco Commerce is able to accept multiple different methods of payment on a Site. Their job is to provide a standard interface between third-party payment gateways and Umbraco Commerce itself. This is done in order to allow the passing of information between the two platforms.

How the integrations work is often different for each payment gateway. The Umbraco Commerce Payment Providers add a flexible interface that should be able to work with most payment gateways.

Example Payment Provider

An example of a bare-bones Payment Provider would look something like this:

All Payment Providers inherit from a base class AsyncPaymentProviderBase<TSettings>. TSettings is the type of a Plain Old Class Object (POCO) model class representing the Payment Providers settings. The class must be decorated with PaymentProviderAttribute which defines the Payment Providers alias, name and description, and can also specify an icon to be displayed in the Umbraco Commerce backoffice.

The settings class consists of a series of properties, each decorated with a PaymentProviderSettingAttribute defining a name, description, and possible angular editor view file. These will all be used to dynamically build an editor interface for the given settings in the backoffice.

Payment Provider Responsibilities

There are two main responsibilities of a Payment Provider, and those are:

• Payment Capture - Capturing the initial Order payment and finalizing the Order.

• Payment Management - Managing a payment post Order finalization, such as being able to Capture authorized payments or Refunding captured payments.

Payment Capture

The Payment Capture workflow can be the hardest part of a Payment Provider. This is due to the fact that no two payment gateways are alike. Therefore it can be difficult to figure out how best to implement the gateway into the provider format.

Generally, there are three methods within a Payment Provider that you may need to implement, and each one has a specific responsibility.

• GenerateForm - The GenerateForm method is responsible for generating an HTML form that will redirect the customer to the given payment gateway payment form. In this method you may need to communicate with the payment gateway in order to initialize a payment, letting the payment gateway know how much to capture. This often results in some kind of code or redirect URL being returned which will need to be embedded into the generated form. The generated form is then usually displayed on a checkout Review page, the last page before payment is captured and will have an implementer-defined Continue to Payment button to submit the form and redirect the customer to the gateway.

• ProcessCallback - The ProcessCallback method is responsible for handling the response coming back from the payment gateway and processing whether the payment was successful or not. This can sometimes occur synchronously, if the payment gateway sends information back as part of the confirmation page redirect, or can occur asynchronously if the payment gateway sends the information back via an out-of-band webhook request.

• GetOrderReference - The GetOrderReference method is responsible for extracting an order reference number from a request when the payment gateway uses an asynchronous webhook to finalize an Order and it uses a global webhook URL strategy for all notifications rather than a notification URL per transaction. Where a webhook URL can be passed per transaction, then Umbraco Commerce provides you with a unique callback URL you can register with the gateway that already identifies the order reference as part of the URL parameters, making implementing this method unnecessary.

* denotes a required method implementation.

What follows is a generalized diagram in order to help in visualizing when each of these methods is called within a regular checkout flow.

Payment Management

In addition to the initial payment capture flow, Payment Providers can also be set up to manage the payment post-checkout. This could be Capturing Authorized transactions or Refunding Captured transactions.

These features are optional and not required for Payment Provider developers to implement. They allow store owners to manage payments directly in the backoffice rather than through the payment gateway's portal when performing these types of actions.

The implementable management methods are:

• FetchPaymentStatus - The FetchPaymentStatus method communicates with the 3rd party payment gateway in order to fetch the current status of the given transaction.

• CapturePayment - The CapturePayment method communicates with the 3rd party payment gateway to capture a previously authorized payment associated with the given transaction.

• CancelPayment - The CancelPayment method communicates with the 3rd party payment gateway to cancel a previously authorized payment associated with the given transaction.

• RefundPayment - The RefundPayment method communicates with the 3rd party payment gateway to refund a previously captured payment associated with the given transaction.

For each implemented method above, developers should also implement a corresponding boolean property returning a true value. This is to let Umbraco Commerce know that the given feature is supported by the Payment Provider.

• CanFetchPaymentStatus

• CanCapturePayments

• CanCancelPayments

• CanRefundPayments

Payment Provider Meta Data

For all implemented methods of a Payment Provider, all method return types support the returning of additional Meta Data. This is to allow Payment Providers to capture and store relevant information. This information will aid the provider in doing its job, or for storing useful reference information to display for the retailer.

Any returned Meta Data from a Payment Provider method will be stored against the Order in its collection. Should you need to retrieve these values from other areas of the Payment Provider, you can use the passed-in Orders Properties collection.

Meta Data Definitions

The Meta Data that is returned from the Payment Provider is useful for the retailer. The Payment Provider can also be used to display Meta Data descriptions and information in the backoffice. This is done by exposing a TransactionMetaDataDefinitions property consisting of a list of TransactionMetaDataDefinition values. Each of the values defines the alias, name and optional description of a Meta Data entry.

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:

1. Register the Template in a Composer:

Print and Export Templates

To create Print/Export Templates:

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

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.

The Customer API endpoints allow fetching all orders associated with a customer.

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.

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.

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.