Umbraco Commerce v14.0.0-Alpha is the initial release of Umbraco Commerce for Umbraco CMS v14. Being an alpha, this is an early preview of the Umbraco Commerce product and as such should be considered a work in progress.

Key Takeaways

Core Functionality

The key focus of this alpha release is to provide the core functionality required to be able to setup and run a store in Umbraco Commerce allowing users to get started on v14 right away.

The key features included in this release are:

• Store Creation / Editing

• Location Creation / Editing

• Order Status Creation / Editing

• Payment Method Creation / Editing

• Shipping Method Creation / Editing

• Country & Region Creation / Editing

• Currency Creation / Editing

• Tax Class Creation / Editing

• Email Template Creation / Editing

• Print Template Creation / Editing

• Export Template Creation / Editing

• Order View / Editing

• Order / Order Line Properties Editing

Missing Features

Within these sections there are some known missing features:

• Missing text filtering on collection views

• Missing bulk operations implementation

• Missing sort functionality

• Missing advanced order searching

• Missing order filter menus

In addition to these, there are also some complete sections currently outstanding:

• Store overview dashboard

• Cart section

• Discounts section

• Gift cards section

• Analytics section

• Product Attributes + Product Attribute Presets section

Lastly, there is also some property editors still yet to implement:

• Variants

Needless to say, these will all be implemented for the final v14 release, but in order to get a usable Umbraco Commerce product into your hands as quickly as possible, these features / sections were put at lower priorities at this stage of the conversion.

Breaking Changes

With the new backoffice UI, there has inevitably been the need to change some functionalities and use such breaking changes couldn't be avoided. These have tried to be minimized as much as possible, whilst also ensuring we embrace the new front end architecture to it's fullest.

The key breaking changes to expect are:

• UI Config Files Remove

  In addition to this, the UI Config Files were also used in the backoffice to extract key order properties for things like extracting the shipping address in order to calculate shipping rates. This functionality has now been split such that this mapping functionality has now moved to a new server based configuration API.

  Copy

  builder.WithOrderPropertyConfigs()
    .Add("myStoreAlias", b => b
        .For(x => x.Customer.FirstName).MapFrom("firstName")
        .For(x => x.Customer.LastName).MapFrom("lastName")
        ...
    );

• Web Notification Events Removed

  The following notifications are no longer being fired.

  • AnalyticsDashboardConfigParsingNotification

  • CartEditorConfigParsingNotification

  • OrderEditorConfigParsingNotification

  • StoreActionsRenderingNotification

  • ActivityLogEntriesRenderingNotification

• Web Controllers / Models Removed

  With the new Management API this does mean any controllers / models that previously lived in the Umbraco.Commerce.Cms.Web will now have been removed. Please use the Management API instead.

  The only exception to this is the PaymentController which is used as a callback for payment gateways. This is currently kept at the same URL to prevent breakages. We will be reviewing this to see if some other endpoint location makes more sense.

UI Extension Points

With the new backoffice comes a new extensions system for the UI and we have tried to use this to the maximum. These means converting the old UI configs system to using the new manifests system.

With the new extension points it is possible to:

• Change the properties used by the order editor.

• Add properties to the order line properties editor.

• Add properties to the Notes, Additional Info and Customer Details modals.

• Add properties to the order collection view.

• Add analytics widgets (still in progress)

• Define custom views for properties to control value rendering.

Here is an example of how you would configure such properties

export const manifests : Array<UcManifestOrderLineProperty> = [
    {
        type: 'ucOrderLineProperty',
        alias: 'Uc.OrderLineProperty.Color',
        name: 'Order Line Color',
        weight: 100,
        meta: {
            propertyAlias: 'color',
            editorUiAlias: 'Umb.PropertyEditorUi.EyeDropper',
            labelElementName: 'uc-mini-color-swatch'
        }
    },
    {
        type: 'ucOrderLineProperty',
        alias: 'Uc.OrderLineProperty.GiftMessage',
        name: 'Order Line Gift Message',
        weight: 100,
        meta: {
            propertyAlias: 'giftMessage',
            editorUiAlias: 'Umb.PropertyEditorUi.TextArea',
            summaryStyle: 'table'
        }
    }
];

With these extension points, the Umbraco Commerce order editor is now more flexible than it has ever been before.

Management API

As with the CMS, with the new UI comes a whole new API layer.

With the Umbraco Commerce API we have aimed to keep it aligned with the Storefront API with support for filtering an expansion where possible.

I key thought whilst developing this API has been to ensure external developers might use this to build other UI's for Umbraco Commerce such as a dedicated mobile app and so we've tried to ensure there are no "special" endpoints just for the Umbraco CMS UI.

Localization

One of the things that has been on the Umbraco Commerce TODO list for a while is to add backoffice localization support. Given the fresh start it was only logical that we take the time to ensure that everything we built fully supported localization so this will be included in this release.

We haven't quite caught everything yet, but we'll be sure to do a full check before the final release to ensure all hard coded strings are fully configurable.

With this update, we'll also be making some changes to things like payment and shipping providers, and other CSharp extension points where we define properties. These will no longer require hard coded labels / descriptions and instead will look these values up from the localization file.

Add-on Updates

We are still yet to tackle adding v14 support to the Umbraco.Commerce.Deploy and Umbraco.Commerce.Checkout add-ons so these are currently unavailable. These will likely be made available after the initial v14 release.

What to Test and How to Give Feedback

We would welcome feedback on any installation / upgrade issues along with bugs found in any of the completed sections as detailed above.

Any breaking changes or important issues to consider when upgrading are also mentioned in this article.

Release History

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

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

• Updated min Umbraco dependency to 14.3.0 in order to implement validation.

14.3.0 (January 13th 2025)

• Added Funnel group match type to Discount rule builder and made All / Any implementations more logical.

• Updated Umbraco.Licenses dependency with latest changes.

14.2.1 (January 8th 2025)

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

• Fixed error in migration script.

14.2.0 (November 12th 2024)

• Added a cart-to-order feature that will facilitate admin users to finalize an order directly from the BackOffice cart workspace.

Important If you are running on version 14 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 UDI parsing error when using product related discount rules due to missing UDI Json Converter. Fixed by backporting PocoFactory from v15.

14.1.1 (27th September 2024)

14.1.0 (25th September 2024)

• Added Tax Calculation Method to allow for calculated tax rates.

• Updated Countries to accept a tax calculation method.

• Updated Tax Classes to support tax codes.

14.0.1 (24th September 2024)

• Fixed broken migration causing exception on upgrade.

14.0.0 (23rd August 2024)

• Added "No results" messages to collection views

• Upgraded Umbraco CMS dependency to v14.2.0

14.0.0-rc3 (12th August 2024)

• Added warning on store dashboard/analytics section if the store has multiple currencies when no currency exchange rate service is configured.

• Added nullable type support to payment provider/shipping provider settings models.

• Added UcStoreContext to exported NPM package.

• Added background task licenses resolver to allow Umbraco Commerce to run background tasks without error.

• Added delete support to carts and orders.

• Updated store create dialog to redirect to store editor on create.

• Fixed errors in v14 migrations when using a separate table for Umbraco Commerce.

• Fixed error in v14 migrations where data types are not correctly migrated.

• Fixed store tree not updating when a new store is created.

• Fixed shipping provider advanced settings now showing in an advanced dropdown editor UI.

• Fixed broken localization keys.

14.0.0-rc2 (29th July 2024)

• Fixed issue in rc1 DB migration script.

14.0.0-rc1 (29th July 2024)

• Added sort modals to all sortable entities.

• Added basic text search across all entity collection views.

• Added cart status filter option to carts collection view.

• Added advanced properties support to payment/shipping provider settings.

• Added order activity log funcationality back in.

• Added commerce section dashboard.

• Added async pipeline implementation.

• Added front end NPM package for UI extension points.

• Localized all hard coded strings.

• Replaced Newtonsoft.Json with System.Text.Json throughout.

• Removed ExchangeRateHost as the default exchange rate service as it now requires an API key.

• Fixed validation error for Region code not matching the description example.

• Fixed bug in payment provider URL generation containing a rogue $ symbol.

14.0.0-beta1 (16th July 2024)

• Added Product Attributes section

• Added Product Attribute Presets section

• Added Variants property editor to create complex product variants

• Fixed issues with property editor value converters

• Fixed issue with stock synchronization

14.0.0-alpha4 (3rd July 2024)

• Added Carts section with ability to create/edit customer carts

• Refactored order endpoints to use a defined model for customer/billing/shipping details rather than using order properties collection

• Merged in v13 bug fixes

14.0.0-alpha3 (24th June 2024)

• Added Analytics section

• Added Create Country modal to allow creating countries from ISO 3166 presets

• Added license warning component throughout the commerce section

• Updated Regions workspace app to now be hidden until the country is persisted

• Update Payment Provider / Shipping Provider label keys to convert kebab case provider aliases to camel case keys for consistency

• Fixed bug in Payment Providers section throwing error due to unmapped sku property

14.0.0-alpha2 (7th June 2024)

• Added section condition to commerce section to only show it when the current user has permission to see it

• Setup Management APIs for Product Attributes, Discounts, Gift Cards and Analytics sections

• Created an new Umbraco Commerce Payment API to handle payment gateway interactions (old endpoints are depricated)

• Added a basic store dashboard with current days stats and order search

• Added Gift Cards section

• Added Discounts section

• Various bug fixes

• Backoffice resources are now lazy loaded

• Upgraded Umbraco dependency to v14 final

14.0.0-alpha1 (24th May 2024)

• v14 initial alpha release

Legacy release notes

In this article, you will find the key steps needed to get started with Umbraco Commerce.

It is assumed that you have an Umbraco 14+ website configured and ready for the Umbraco Commerce installation.

System Requirements

The minimum requirements for using Umbraco Commerce are:

• Umbraco CMS version 14+

• SQL Server 2015+ Database

Versioning

This release marks the v14 build of Umbraco Commerce, now feature complete and ready for developers to start using it.

Key Takeaways

New Backoffice UI

As with everything v14, this is a complete rebuild of the backoffice UI using web components. This ensures Umbraco Commerce is set for the future and creates a solid foundation to develop new features and functionality.

Breaking Changes

With the new backoffice UI, there has inevitably been the need to change some functionalities, and as such breaking changes could not be avoided. These have tried to be minimized as much as possible, whilst also ensuring we embrace the new front-end architecture to its fullest.

The key breaking changes to expect are:

• UI Config Files Removed

In addition to this, the UI config files were also used in the backoffice to extract key order properties. For example, extracting the shipping address to calculate shipping rates. This functionality has now been split, and the mapping functionality has been moved to a new server-based configuration API.

builder.WithOrderPropertyConfigs()
  .Add("myStoreAlias", b => b
      .For(x => x.Customer.FirstName).MapFrom("firstName")
      .For(x => x.Customer.LastName).MapFrom("lastName")
      ...
  );

• Web Notification Events Removed

  The following notifications are no longer being fired:

  • AnalyticsDashboardConfigParsingNotification

  • CartEditorConfigParsingNotification

  • OrderEditorConfigParsingNotification

  • StoreActionsRenderingNotification

  • ActivityLogEntriesRenderingNotification

• Web Controllers/Models Removed

With the new Management API, any controllers or models previously located in Umbraco.Commerce.Cms.Web have been removed. Please use the Management API instead.

The only exception to this rule is the PaymentController, which serves as a callback for payment gateways. It is currently located at the same URL to avoid disrupting existing transaction communications. However, all new integrations should communicate with a new Payments API.

UI Extension Points

With the new backoffice comes a new extensions system for the UI, and we have tried to maximize its use. This means converting the old UI configs system to use the new manifests system.

With the new extension points it is possible to:

• Change the properties used by the order editor.

• Add properties to the order line properties editor.

• Add properties to the Notes, Additional Info, and Customer Details modals.

• Add properties to the order collection view.

• Add analytics widgets (still in progress)

• Define custom views for properties to control value rendering.

Here is an example of how you would configure these properties:

export const manifests : Array<UcManifestOrderLineProperty> = [
    {
        type: 'ucOrderLineProperty',
        alias: 'Uc.OrderLineProperty.Color',
        name: 'Order Line Color',
        weight: 100,
        meta: {
            propertyAlias: 'color',
            editorUiAlias: 'Umb.PropertyEditorUi.EyeDropper',
            labelElementName: 'uc-mini-color-swatch'
        }
    },
    {
        type: 'ucOrderLineProperty',
        alias: 'Uc.OrderLineProperty.GiftMessage',
        name: 'Order Line Gift Message',
        weight: 100,
        meta: {
            propertyAlias: 'giftMessage',
            editorUiAlias: 'Umb.PropertyEditorUi.TextArea',
            summaryStyle: 'table'
        }
    }
];

With these extension points, the Umbraco Commerce order editor is now more flexible than it has ever been before.

Management API

With the new UI, a new API layer is also introduced, similar to the CMS.

With the Umbraco Commerce API, we have aimed to keep it aligned with the Storefront API with support for filtering and expansion where possible.

We developed this API for external developers who can use it to create different UIs for Umbraco Commerce, such as a dedicated mobile app. We have made sure that there are no "special" endpoints exclusively for the Umbraco CMS UI.

Localization

Given the fresh start, we made sure that everything we built fully supports localization, so this will be included in this release.

In this update, we have made some changes to payment and shipping providers, as well as other CSharp extension points where properties are defined. These changes mean that labels and descriptions will no longer be hard-coded; instead, the values will be looked up from the localization file.

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

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

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

How does it work?

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

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

The license will cover the following domains:

• localhost

• *.local

• *.mysite.com

• www.mysite.com

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What does a license cover?

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

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

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

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

• The license allows for an unlimited number of orders.

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

Configuring your license

Add additional domains

Installing your license

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

1. Open the root directory for your project files.

2. Locate and open the appSettings.json file.

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

"Umbraco": {
    "Licenses": {
        "Products": {
            "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/"
            }
        }
    }
}

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.

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

Key changes

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

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

Project, Package, and Namespace changes

Step 1: Replace dependencies

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

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

dotnet remove package Vendr

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

2. Delete the Vendr App_Plugins folder:

rmdir App_Plugins\Vendr

1. Install Umbraco.Commerce:

dotnet add package Umbraco.Commerce

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

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

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

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

5. Compile your project against .NET 7.0.

Step 2: Update namespaces and entity names

Step 3: Update the database

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

1. Backup your database

2. Rename database tables using the following query:

sp_rename vendrCurrency, umbracoCommerceCurrency;
sp_rename vendrTaxClass, umbracoCommerceTaxClass;
sp_rename vendrStock, umbracoCommerceStock;
sp_rename vendrOrderStatus, umbracoCommerceOrderStatus;
sp_rename vendrEmailTemplate, umbracoCommerceEmailTemplate;
sp_rename vendrPaymentMethod, umbracoCommercePaymentMethod;
sp_rename vendrShippingMethod, umbracoCommerceShippingMethod;
sp_rename vendrCountry, umbracoCommerceCountry;
sp_rename vendrRegion, umbracoCommerceRegion;
sp_rename vendrCurrencyAllowedCountry, umbracoCommerceCurrencyAllowedCountry;
sp_rename vendrPaymentMethodAllowedCountryRegion, umbracoCommercePaymentMethodAllowedCountryRegion;
sp_rename vendrPaymentMethodCountryRegionPrice, umbracoCommercePaymentMethodCountryRegionPrice;
sp_rename vendrPaymentMethodPaymentProviderSetting, umbracoCommercePaymentMethodPaymentProviderSetting;
sp_rename vendrShippingMethodAllowedCountryRegion, umbracoCommerceShippingMethodAllowedCountryRegion;
sp_rename vendrShippingMethodCountryRegionPrice, umbracoCommerceShippingMethodCountryRegionPrice;
sp_rename vendrTaxClassCountryRegionTaxRate, umbracoCommerceTaxClassCountryRegionTaxRate;
sp_rename vendrDiscount, umbracoCommerceDiscount;
sp_rename vendrDiscountCode, umbracoCommerceDiscountCode;
sp_rename vendrOrder, umbracoCommerceOrder;
sp_rename vendrOrderProperty, umbracoCommerceOrderProperty;
sp_rename vendrOrderLine, umbracoCommerceOrderLine;
sp_rename vendrOrderLineProperty, umbracoCommerceOrderLineProperty;
sp_rename vendrGiftCard, umbracoCommerceGiftCard;
sp_rename vendrOrderAppliedDiscountCode, umbracoCommerceOrderAppliedDiscountCode;
sp_rename vendrOrderAppliedGiftCard, umbracoCommerceOrderAppliedGiftCard;
sp_rename vendrStoreAllowedUserRole, umbracoCommerceStoreAllowedUserRole;
sp_rename vendrStoreAllowedUser, umbracoCommerceStoreAllowedUser;
sp_rename vendrFrozenPrice, umbracoCommerceFrozenPrice;
sp_rename vendrGiftCardProperty, umbracoCommerceGiftCardProperty;
sp_rename vendrActivityLog, umbracoCommerceActivityLog;
sp_rename vendrOrderPriceAdjustment, umbracoCommerceOrderPriceAdjustment;
sp_rename vendrOrderAmountAdjustment, umbracoCommerceOrderAmountAdjustment;
sp_rename vendrProductAttribute, umbracoCommerceProductAttribute;
sp_rename vendrProductAttributeValue, umbracoCommerceProductAttributeValue;
sp_rename vendrTranslatedValue, umbracoCommerceTranslatedValue;
sp_rename vendrProductAttributePreset, umbracoCommerceProductAttributePreset;
sp_rename vendrProductAttributePresetAllowedAttribute, umbracoCommerceProductAttributePresetAllowedAttribute;
sp_rename vendrOrderLineAttribute, umbracoCommerceOrderLineAttribute;
sp_rename vendrPrintTemplate, umbracoCommercePrintTemplate;
sp_rename vendrExportTemplate, umbracoCommerceExportTemplate;
sp_rename vendrStoreEntityTag, umbracoCommerceStoreEntityTag;
sp_rename vendrMigrations, umbracoCommerceMigrations;
sp_rename vendrStore, umbracoCommerceStore;

ALTER TABLE vendrCurrency RENAME TO umbracoCommerceCurrency;
ALTER TABLE vendrTaxClass RENAME TO umbracoCommerceTaxClass;
ALTER TABLE vendrStock RENAME TO umbracoCommerceStock;
ALTER TABLE vendrOrderStatus RENAME TO umbracoCommerceOrderStatus;
ALTER TABLE vendrEmailTemplate RENAME TO umbracoCommerceEmailTemplate;
ALTER TABLE vendrPaymentMethod RENAME TO umbracoCommercePaymentMethod;
ALTER TABLE vendrShippingMethod RENAME TO umbracoCommerceShippingMethod;
ALTER TABLE vendrCountry RENAME TO umbracoCommerceCountry;
ALTER TABLE vendrRegion RENAME TO umbracoCommerceRegion;
ALTER TABLE vendrCurrencyAllowedCountry RENAME TO umbracoCommerceCurrencyAllowedCountry;
ALTER TABLE vendrPaymentMethodAllowedCountryRegion RENAME TO umbracoCommercePaymentMethodAllowedCountryRegion;
ALTER TABLE vendrPaymentMethodCountryRegionPrice RENAME TO umbracoCommercePaymentMethodCountryRegionPrice;
ALTER TABLE vendrPaymentMethodPaymentProviderSetting RENAME TO umbracoCommercePaymentMethodPaymentProviderSetting;
ALTER TABLE vendrShippingMethodAllowedCountryRegion RENAME TO umbracoCommerceShippingMethodAllowedCountryRegion;
ALTER TABLE vendrShippingMethodCountryRegionPrice RENAME TO umbracoCommerceShippingMethodCountryRegionPrice;
ALTER TABLE vendrTaxClassCountryRegionTaxRate RENAME TO umbracoCommerceTaxClassCountryRegionTaxRate;
ALTER TABLE vendrDiscount RENAME TO umbracoCommerceDiscount;
ALTER TABLE vendrDiscountCode RENAME TO umbracoCommerceDiscountCode;
ALTER TABLE vendrOrder RENAME TO umbracoCommerceOrder;
ALTER TABLE vendrOrderProperty RENAME TO umbracoCommerceOrderProperty;
ALTER TABLE vendrOrderLine RENAME TO umbracoCommerceOrderLine;
ALTER TABLE vendrOrderLineProperty RENAME TO umbracoCommerceOrderLineProperty;
ALTER TABLE vendrGiftCard RENAME TO umbracoCommerceGiftCard;
ALTER TABLE vendrOrderAppliedDiscountCode RENAME TO umbracoCommerceOrderAppliedDiscountCode;
ALTER TABLE vendrOrderAppliedGiftCard RENAME TO umbracoCommerceOrderAppliedGiftCard;
ALTER TABLE vendrStoreAllowedUserRole RENAME TO umbracoCommerceStoreAllowedUserRole;
ALTER TABLE vendrStoreAllowedUser RENAME TO umbracoCommerceStoreAllowedUser;
ALTER TABLE vendrFrozenPrice RENAME TO umbracoCommerceFrozenPrice;
ALTER TABLE vendrGiftCardProperty RENAME TO umbracoCommerceGiftCardProperty;
ALTER TABLE vendrActivityLog RENAME TO umbracoCommerceActivityLog;
ALTER TABLE vendrOrderPriceAdjustment RENAME TO umbracoCommerceOrderPriceAdjustment;
ALTER TABLE vendrOrderAmountAdjustment RENAME TO umbracoCommerceOrderAmountAdjustment;
ALTER TABLE vendrProductAttribute RENAME TO umbracoCommerceProductAttribute;
ALTER TABLE vendrProductAttributeValue RENAME TO umbracoCommerceProductAttributeValue;
ALTER TABLE vendrTranslatedValue RENAME TO umbracoCommerceTranslatedValue;
ALTER TABLE vendrProductAttributePreset RENAME TO umbracoCommerceProductAttributePreset;
ALTER TABLE vendrProductAttributePresetAllowedAttribute RENAME TO umbracoCommerceProductAttributePresetAllowedAttribute;
ALTER TABLE vendrOrderLineAttribute RENAME TO umbracoCommerceOrderLineAttribute;
ALTER TABLE vendrPrintTemplate RENAME TO umbracoCommercePrintTemplate;
ALTER TABLE vendrExportTemplate RENAME TO umbracoCommerceExportTemplate;
ALTER TABLE vendrStoreEntityTag RENAME TO umbracoCommerceStoreEntityTag;
ALTER TABLE vendrMigrations RENAME TO umbracoCommerceMigrations;
ALTER TABLE vendrStore RENAME TO umbracoCommerceStore;

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

UPDATE umbracoDataType
SET propertyEditorAlias = REPLACE(propertyEditorAlias, 'Vendr.', 'Umbraco.Commerce.')
WHERE propertyEditorAlias LIKE 'Vendr.%'

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

UPDATE umbracoPropertyData
SET textValue = REPLACE(textValue, 'Vendr.VariantsEditor', 'Umbraco.Commerce.VariantsEditor')
WHERE textValue LIKE '%Vendr.VariantsEditor%';

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

UPDATE umbracoCommerceOrderPriceAdjustment
SET type = REPLACE(type, 'Vendr.', 'Umbraco.Commerce.')
WHERE type LIKE '%Vendr.%';
UPDATE umbracoCommerceOrderAmountAdjustment
SET type = REPLACE(type, 'Vendr.', 'Umbraco.Commerce.')
WHERE type LIKE '%Vendr.%';

1. Update template paths:

UPDATE umbracoCommerceEmailTemplate
SET templateView = REPLACE(templateView, '/App_Plugins/Vendr/templates/email', '/Views/UmbracoCommerce/Templates/Email')
WHERE templateView LIKE '%/Vendr/%';
UPDATE umbracoCommercePrintTemplate
SET templateView = REPLACE(templateView, '/App_Plugins/Vendr/templates/print', '/Views/UmbracoCommerce/Templates/Print')
WHERE templateView LIKE '%/Vendr/%';
UPDATE umbracoCommerceExportTemplate
SET templateView = REPLACE(templateView, '/App_Plugins/Vendr/templates/export', '/Views/UmbracoCommerce/Templates/Export')
WHERE templateView LIKE '%/Vendr/%';

1. Update the migrations log:

UPDATE umbracoCommerceMigrations
SET migration = REPLACE(migration, 'Vendr.', 'Umbraco.Commerce.')
WHERE migration LIKE 'Vendr.%';

1. Update the activity logs:

UPDATE umbracoCommerceActivityLog
SET eventType = REPLACE(eventType, 'vendr/', 'commerce/')
WHERE eventType LIKE 'vendr/%';

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:

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

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

https://{site_url}/umbraco/commerce/payment/callback/{payment_provider_alias}/{payment_method_id}/

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:

In this article, you will learn how to install Umbraco Commerce into your Umbraco CMS implementation.

Prerequisites

Umbraco Commerce Installation

There are different ways to install Umbraco Commerce:

NuGet Package Installation

To install Umbraco Commerce via NuGet:

1. Run the following command in the NuGet Manager Console window:
2. Restart the application using the following command:

Visual Studio Installation

To install via Visual Studio, follow these steps:

1. Open your project in Visual Studio.

2. Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution...

3. Browse for Umbraco.Commerce.
4. Select the appropriate version from the Version drop-down depending on the Umbraco version you are using.

5. Click Install.

6. Ensure that the package reference is added to the .csproj file once the installation is complete:

For most projects, you only need a single package to install Umbraco Commerce. But if your solution is more complex with multiple projects, Umbraco Commerce provides sub-packages to match different dependencies.

Installing a License

Using Umbraco Commerce

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

Version Specific Upgrade Notes History

14.1.0

• Tax Classes now have Country Region Tax Classes rather than Country Region Tax Rates so that tax codes can be assigned to products. Developers should update any references for Country Region Tax Rates to Country Region Tax Classes.

14.0.0

• UI Config file configurations will need to use the new UI Extensions API

Umbraco Commerce Launch

Umbraco Commerce contains a number of breaking changes from the previous Vendr product.

Legacy version specific upgrade notes

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. Allow that User Group access to the Commerce section as a whole.

5. Click Save.

6. Navigate to the Users section.

7. Click on the User.

8. Choose Commerce in the Groups field to assign the user access to the Commerce section.

9. Click Save.

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

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.

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:

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

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 a number of key areas of configuration accessible within the Settings section:

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

• Locations contain the configuration of the different locations of the store.

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

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

• Export Templates contains the list of Export 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.

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.

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

1. Remove any installed Umbraco Commerce packages

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

1. Update any namespace references.

2. Update project framework to net7.0.

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

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

Available guides

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

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

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.

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

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.

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

Currency Exchange Rate Services

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

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

If you have multiple currencies enabled but have not configured an exchange rate service, Umbraco Commerce will display a warning. This alert appears on the store dashboard and analytics section, indicating that the reported data may be inaccurate.

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.

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.

Registering Dependencies

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

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

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

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

Replacing Dependencies

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

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

Injecting Dependencies

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

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 there are a number of Umbraco Commerce-specific concepts you will need to be aware of.

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 Rate Services

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

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

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

Adding the Controller

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

Create a new Controller called CartSurfaceController.cs

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

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

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

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

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

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

• SaveOrder is called to save the order.

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

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

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:

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.

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.

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

Labels

Both the DiscountRuleProviderAttribute and the DiscountRewardProviderAttribute allow you to define a LabelUiAlias for the Provider. This should be the alias of a UI component registered as a Property Editor UI implementation.

A basic label component is defined as follows:

The component will pass a Record<string, unknown> value representing the rule/rewards configured values. Use this value to create your label.

Once defined, your component can be registered as a Property Editor UI via a manifest entry.

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

Localization

Umbraco Commerce will automatically look for the following entries:

Here {type} can be either Rule or Reward. {providerAlias} is the alias of the rule/reward provider, and {settingAlias} is the alias of a setting.

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.

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:

_priceFreezerService.ThawPrices(partialKey: "c0296b75-1764-4f62-b59c-7005c2348fdd");

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

_priceFreezerService.ThawPrices(currencyId: currency.Id, olderThan: DateTime.Now.AddDays(-30));

Umbraco.Commerce.Core.Events.Validation

Order Payment Events

Country Payment Events

Currency Payment Events

Discount Payment Events

Email Template Payment Events