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

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:

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

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 Umbraco Commerce unrestricted locally without the need for a license. Running Umbraco Commerce in the public domain will display a warning banner in the backoffice and will limit the maximum number of orders to 20. To remove these restrictions, you'll need to have a valid license.

How does it work?

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

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

The license will cover the following domains:

• localhost

• *.local

• *.mysite.com

• www.mysite.com

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What does a license cover?

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

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

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

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

• The license allows for an unlimited number of orders.

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

Configuring your license

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

"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 license dashboard which should display the status of your license.

When and how to configure an UmbracoApplicationUrl

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

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

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

{
    "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 Program.cs:

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 Program.cs file.

Validating a license without an outgoing Internet connection

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

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

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

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

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

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

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

  "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 the value of the authorization key you have configured should be provided.

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

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

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 dynamic shipping rates feature for range based rates calculaton.

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

• A number of API updates to accomodate the new shipping features.

• Add-on updates 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 Dynamic Shipping Rates 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 Shipping Range & Rate Providers 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 Realtime Shipping Rates documentation for how to get started with them.

Shipping Providers

The secret behind realtime rates is the new Shipping Providers 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:

• DHL

• Shipmondo

• EasyPost

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 Shipping Packing Factories 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.

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

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

NuGet Package Installation

Umbraco Commerce is available via NuGet.Org.

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

PM> dotnet add package Umbraco.Commerce

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

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

Installing a License

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

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.

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

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

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

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.

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.

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.

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

Available guides

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

• The existing stock value of the product, and

• The existing quantity of the product in the cart.

ProductAddValidationHandler

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

OrderLineQuantityValidationHandler

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

Register event handlers

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

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 for more details.

Versioning

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

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:

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.

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

    @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.Hidden($"orderLines[{item.Index}].Quantity", (int)item.OrderLine.Quantity, new { @type = "number" })
            @Html.Hidden($"orderLines[{item.Index}].ProductReference", item.OrderLine.ProductReference)
            <a href="@Url.SurfaceAction("RemoveFromCart", "CartSurface", new { OrderLineId = item.OrderLine.Id })">Remove Item</a>
        </p>

    }

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

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

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

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

<a href="@Url.SurfaceAction("RemoveFromCart", "BasketSurface", new { OrderLineId = item.OrderLine.Id })">Remove</a>

Adding the Controller

For the button to work, you need to add some functionality via a 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 example below 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 used to pass data to the Controller. In this instance, it passes over the OrderLineId.

    public class CartDto
    {
        public Guid OrderLineId { get; set; }
    }

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

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

            if (store == null) return;

            var order = _commerceApi.GetOrCreateCurrentOrder(store.Id)
            .AsWritable(uow)
            .RemoveOrderLine(cart.OrderLineId);

            _commerceApi.SaveOrder(order);

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

        return CurrentUmbracoPage();
    }

    TempData["SuccessMessage"] = "Item removed";

    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.

• 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 Add item to cart 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.

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: The Backoffice tutorial.

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

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

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

• productTitle: TextString

• productDescription: TextArea

• price: Umbraco Commerce Price

• stock: Umbraco Commerce Stock

The Product Page template can be implemented as shown below.

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

The code above does the following:

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

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

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

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

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

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

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

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

}

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

Adding the Controller

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

Create a new Controller called CartSurfaceController.cs.

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

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

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

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

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

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

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

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

        if (store == null) return;

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

            commerceApi.SaveOrder(order);

            uow.Complete();

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

The code above does the following:

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

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

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

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

• SaveOrder is called to save the order.

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

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

Add a partial view to display the message

Create a new partial view called Feedback.cshtml.

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

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

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

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

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

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

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

Currency Exchange Rates

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

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

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

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.

App_Plugins\MyPlugin\backoffice\config\umbraco-commerce-bulk-actions-config.js

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

App_Plugins\MyPlugin\package.manifest

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

{
    "javascript": [
        "~/App_Plugins/MyPlugin/backoffice/config/umbraco-commerce-bulk-actions-config.js"
    ]
}

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

angular.module('umbraco.commerce')
    .config(['ucActionsProvider', function (ucActionsProvider) {
        ucActionsProvider.bulkActions.push(['myResource', function (myResource)
        {
            return {
                name: 'My Action',
                icon: 'icon-box',
                itemAction: function (bulkItem) {
                    return myResource.doAction(bulkItem.id);
                },
                condition: function (ctx) {
                    return ctx.entityType == 'Order'
                },
                sortOrder: 110
            }
        }]);
    }]);

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:

angular.module('umbraco.commerce')
    .config(['ucActionsProvider', function (ucActionsProvider) {
        ucActionsProvider.bulkActions.push(['$q', 'editorService', 'myResource', function ($q, editorService, myResource)
        {
            return {
                name: 'My Action',
                icon: 'icon-box',
                configure: function (selected) {
                    return $q(function (resolve, reject) {
                        editorService.open({
                            view: '/app_plugins/myplugin/views/dialogs/config.html',
                            size: 'small',
                            config: {
                                items: selected
                            },
                            submit: function (model) {
                                editorService.close();
                                resolve(model);
                            },
                            close: function () {
                                editorService.close();
                                reject();
                            }
                        });
                    });
                },
                bulkAction: function (items) {
                    var ids = items.map(itm => itm.id);
                    return myResource.doAction(ids);
                },
                condition: function (ctx) {
                    return ctx.entityType == 'Order'
                },
                sortOrder: 110
            }
        }]);
    }]);