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

Version Specific Upgrade Notes History

Version 10 is the initial Long-term support (LTS) release of the Umbraco Commerce product. It contains a number of breaking changes from the previous, Vendr product.

See the Migrate from Vendr to Umbraco Commerce guide for full details.

Legacy version specific upgrade notes

You can find the version specific upgrade notes for versions out of support in the Legacy documentation on Github.

In this section, we have summarized the changes to Umbraco Commerce released in each version. Each version is presented with 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 10 including all changes for this version.

10.0.13 (July 11th 2024)

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

10.0.12 (July 3rd 2024)

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

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

10.0.11 (April 23rd 2024)

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

10.0.10 (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 10.0.9) #472.

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

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

10.0.8 (March 3rd 2024)

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

10.0.7 (February 15th 2024)

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

• Incremented Newtonsoft.Json version dependency to 13.0.1 as 13.0.0 doesn't exist on NuGet anymore #451.

10.0.6 (February 6th 2024)

• 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

10.0.5 (December 13th 2023)

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

10.0.4 (November 1st 2023)

• Use Microsoft.Data.SqlClient for migrations to support Azure connection strings #443.

• Move system config files to system.{}.config.json to allow overriding as per the docs #448.

• Updated order/cart editor config to allow template option for custom property rendering #446.

10.0.3 (October 18th 2023)

• Fixed UI spelling mistakes as documented in issue #427.

• Fixed issue where adding a product with a uniqueness property, and then adding the same product without a uniqueness property would replace the initial orderline, rather than adding a new one #438

• Fixed localization issue where -1 in querystrings would get incorrectly formatted. Root ids are now formatted with an invarient culture.

10.0.2 (September 13th 2023)

• Allow overriding of SameSite/Path for Umbraco Commerce cookies.

• Updated productSource resolution to check for both IPublishedContent and IEnumerable<IPublishedContent> as it depends on the picker used and what its return type is.

10.0.1 (August 15th 2023)

• Updated default order number template from CART-{0} to ORDER-{0}.

• Updated product adapter to resolve product details correctly from child node variants.

10.0.0 (July 5th 2023)

• Initial product launch.

Legacy release notes

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

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.

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

How does it work?

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

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

The license will cover the following domains:

• localhost

• *.local

• *.mysite.com

• www.mysite.com

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What does a license cover?

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

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

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

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

• The license allows for an unlimited number of orders.

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

Configuring your license

You can look at the pricing, features, and purchase a license on the Umbraco Commerce page. A member of the sales team will manage this process. You will need to provide all domains you wish to have covered by the license such as primary and development/staging/QA domains. You should then receive a license code to be installed in your solution.

Add additional domains

If you require to add addition domains to the license, reach out the sales team with your request and they will manage this process.

Installing your license

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

1. Open the root directory for your project files.

2. Locate and open the appSettings.json file.

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

"Umbraco": {
  "Licenses": {
    "Umbraco.Commerce": "YOUR_LICENSE_KEY"
  }
}

Verify the license installation

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

When and how to configure an UmbracoApplicationUrl

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

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

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

{
    "Umbraco": {
        "CMS": {
            "WebRouting": {
                "UmbracoApplicationUrl": "https://admin.my-custom-domain.com/"
            }
        }
    }
}

See the Fixed Application URL documentation for more details about this setting.

Configuring UmbracoApplicationUrl on Umbraco Cloud

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

There are two options in this case:

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

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

For example, in your Startup.cs file, you can add the following to the ConfigureServices method:

services.Configure<WebRoutingSettings>(o => o.UmbracoApplicationUrl = "<your application URL>");

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

Validating a license without an outgoing Internet connection

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

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

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

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

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

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

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

  "Umbraco": {
    "Licenses": {
      "Umbraco.Commerce": "<your license key>"
    },
    "LicensesOptions": {
      "EnableScheduledValidation": false,
      "ValidatedLicenseRelayAuthKey": "<your authorization key>"
    }

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

POST https://license-validation.umbraco.com/api/ValidateLicense
{
    "ProductId": "Umbraco.Commerce",
    "LicenseKey": "<your license key>",
    "Domain": "<your licensed domain>"
}

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

POST http://<your umbraco environment>/umbraco/licenses/validatedLicense/relay?productId=<product id>&licenseKey=<license key>

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

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

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.

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

Get the latest version of Umbraco Commerce

To upgrade to the latest version of Umbraco Commerce you can use:

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

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

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

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

You can find details on migrating the Checkout package as well as custom Payment Providers in the of this article.

Key changes

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

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

Project, Package, and Namespace changes

Step 1: Replace dependencies

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

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

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

2. Delete the Vendr App_Plugins folder:

1. Install Umbraco.Commerce:

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

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

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

5. Compile your project against .NET 7.0.

Step 2: Update namespaces and entity names

Step 3: Update the database

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

1. Backup your database

2. Rename database tables using the following query:

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

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

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

1. Update template paths:

1. Update the migrations log:

1. Update the activity logs:

Step 4: Finalizing the migration

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

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

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

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

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

1. Run the project.

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

Further Migrations

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

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

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 , as well as C# and MVC principals.

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

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.

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 .

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.

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 10+ website configured, and ready to install Umbraco Commerce.

System Requirements

The minimum requirements for using Umbraco Commerce are as follows:

• Umbraco CMS version 10+

• SQL Server 2015+ Database

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

Versioning

This is an add-on product to Umbraco CMS. Umbraco Commerce follows the .

By default, Umbraco Commerce will use the same database as Umbraco to store its data. 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.

{
    ...
    "ConnectionStrings": {
        "umbracoDbDSN": "Server=umbracoServerAddress;Database=myUmbracoDb;User Id=myUsername;Password=myPassword;",
        "umbracoDbDSN_ProviderName": "Microsoft.Data.SqlClient",
        "umbracoCommerceDbDSN": "Server=umbracoCommerceServerAddress;Database=myUmbracoCommerceDb;User Id=myUsername;Password=myPassword;",
        "umbracoCommerceDbDSN_ProviderName": "Microsoft.Data.SqlClient"
    },
    ...
}

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

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"
    },
    ...
}

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.

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

        var totalQuantities = order?.OrderLines.Where(x => x.ProductReference == productReference).Sum(x => x.Quantity) ?? 0;

        if (stock.HasValue && totalQuantities >= 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(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;
    }
}

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 section, we will provide a series of How-To Guides, showcasing how to perform specific tasks within Umbraco Commerce.

Available guides

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

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

Injecting a Bulk Action

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

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

1. Create a custom folder in the App_Plugins directory.

2. Create a JavaScript file with this new folder.

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

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

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

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

Bulk Action Options

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

Important Notes

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

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

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

Examples

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

An added side effect of having 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:

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

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 Startup class, inside the ConfigureServices method 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 ConfigureServices method. 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.

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

Example: Validation event handler

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

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

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.

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.

Example: Notification event handler

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

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

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

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

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

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

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

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

Example Payment Form

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

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

When extending the calculation process of Umbraco Commerce, either by custom or custom 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

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.

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

• When a Discount should apply.

• What the Reward should be for that Discount.

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

Discount Rules

There are two types of Discount Rules in Umbraco Commerce:

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

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

Example: Custom Order Discount Rule Provider

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

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

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

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

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

Example: Custom Order Line Discount Rule Provider

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

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

Discount Rewards

Example: Custom Discount Reward Provider

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

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

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

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

Common Features

Settings Objects

Label Views

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

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

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

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

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

In some cases, you may want to tweak the figures of an order. It could be reducing the price of a product if a customer purchases a given amount of a product. To handle this, Umbraco Commerce has the concept of Price/Amount Adjustments. What adjustments allow you to do is create a record/log of any changes that occur to a price/amount throughout the calculation process. Umbraco Commerce uses the adjustments in the calculation process to work out its final pricing and provides this list of the adjustments on the order. This makes it clear exactly how the price was calculated.

Umbraco Commerce has two types of adjustments:

• Price Adjustment - Adjusts one of the orders' price properties (discounts, fees).

• Amount Adjustment - Adjusts the final transaction amount of the order (gift cards, loyalty points).

Creating Custom Adjustments

Adjustments are applied using a IPriceAdjuster or IAmountAdjuster with developers able to create their own adjusters to apply custom adjustments.

Adjusters apply adjustments to the given price they wish to affect. Adjustments are strongly typed and each adjuster should define their own adjustment type, providing properties to collect any relevant information for the adjustment. This "metadata" gets serialized with the adjustment as is constantly available when accessing the given adjustment.

Adjustments inherit from either PriceAdjustment<TSelf> or AmountAdjustment<TSelf> depending on the type of adjustment being applied. Both base classes follow a similar structure, the difference being whether the adjustment value is a Price or Amount.

Once defined, the adjuster should be registered with the DI container to enable Umbraco Commerce to be aware of it and include it in the calculation process.

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:

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

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.