This documentation platform covers only major versions of Umbraco Commerce. If you are using an unsupported version, you need to go elsewhere.

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 This Documentation

This documentation is aimed at developers who have at least a basic understanding of , as well as C# and MVC principals.

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

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 feature for up to the minute, shipping operator shipping quotes.

• A number of to accomodate the new shipping features.

• are also neccesarry for this release.

Dynamic Shipping Rates

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

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

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

Range / Rate Providers

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

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

Realtime Shipping Rates

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

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

Shipping Providers

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

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

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

API Updates

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

Locations / Store Default Location

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

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

Shipping Packing Factories

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

See the concept documentation for more details.

Measurements Property Editor / Store Measurement System

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

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

C# / Storefront API Updates

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

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

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

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

Add-on Updates

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

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

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

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

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

Purchasing your license

You can look at the pricing, features, and purchase a license on the 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, with your request and they will manage this process.

Configuring your license

Once you've purchased your license with the correct domains, you are ready to configure the license key on your Umbraco installation.

The license key should be added to your configuration using product ID: Umbraco.Commerce.

For detailed instructions on how to install and configure your license, including version-specific examples and additional configuration options, see the article.

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 .

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

Accessing the Default Built-in Templates

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

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

In this section, we have summarized the changes to Umbraco Commerce that were released in each version. Each version has a link to the 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.

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

Available guides

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.

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

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

The Store API endpoints allow fetching supported store details.

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.

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

Webhooks

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

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

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.

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.

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

Stacked Shortest Dimension Package Factory

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

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

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

Limitations

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

• Assumes items can be stacked in any orientation

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

Custom Package Factory

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

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

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

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

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

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

Controlling Price Freezing

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

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

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

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

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

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

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

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

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

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

Changing the Tax Source Factory

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

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

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

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

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

Example Payment Form

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

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

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

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

Configuration

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

• Click Create Shipping Method

• Choose the Basic shipping provider

• Chose the Fixed calculation mode option

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

• Enter a fixed rate for the shipping method

• Configure the countries this shipping method should be allowed in

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

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

Creating a Bundle

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

Adding Sub Products to a Bundle

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

Order Line Price Calculation

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

Displaying Bundles in the Back-Office

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

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 .

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

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

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

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

Fixed Rate Shipping

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

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

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

Shipping Calculators

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

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

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

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

The settings objects have a number of responsibilities.

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

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.

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

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

Child Variants

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

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.

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

Configuration

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

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

Writing fluently

You could perform a write operation as follows:

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

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

Hosted

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

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

Configuring Realtime Rate Shipping

To configure Realtime Rate Shipping, follow these steps:

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.

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

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

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

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

Consider these use-case examples:

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

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

Example Pipeline task

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

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

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

Registering a Pipeline task

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

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

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

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

Specifications

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

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

Searching

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

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

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

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

Ordering Results

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

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

Properties

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 API and is the default option.

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

• CurrencyLayerCurrencyExchangeRateService uses the 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 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:

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.

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

Why have ReadOnly and Writable entities?

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

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

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

Converting a ReadOnly entity into a Writable entity

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

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

Shipping Rate Range Provider

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

System Shipping Rate Ranger Providers

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

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

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

Custom Shipping Rate Range Providers

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

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

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

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

• Store - The store the order belongs to.

Registering your custom Shipping Rate Range Provider

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

Shipping Rate Provider

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

System Shipping Rate Providers

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

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

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

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

Custom Shipping Rate Providers

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

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

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

• Order - The order associated with this calculation.

• Store - The store the order belongs to.

Registering your custom Shipping Rate Provider

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

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

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

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

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

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

• IOrderCalculator - Responsible for calculating the entire Order.

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

Defining a Custom Calculator Implementation

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

Registering a custom Calculator implementation

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

Shipping Providers are how Umbraco Commerce can perform real-time shipping operations. Their job is to provide a standard interface between third-party shipping operators and Umbraco Commerce. This is done to allow the passing of information between the two platforms.

How the integrations work is often different for each shipping operator. The Umbraco Commerce Shipping Providers add a flexible interface that should work with most shipping operators.

Example Shipping Provider

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

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

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

Shipping Provider Responsibilities

The responsibilities of a Shipping Provider are:

• Realtime Rates - Calculating shipping rate options for a given Order.

Realtime Rates

Real-time rates are returned by implementing the GetShippingRatesAsync method. To facilitate rate calculation, a ShippingProviderContext object is passed to this method providing useful, contextual information, including:

• Order - The Order and its items to be shipped.

• MeasurementSystem - The measurement system of the Store associated with the given Order.

• Packages - A list of packages that make up this shipment. Each package contains a reference of the order lines it contains, its overall dimensions and weight, and both sender and receiver address details. See the for more details on how these are created.

Implementors should use these details to pass to the 3rd party shipping operators API and retrieve the estimated shipping costs. These should then be returned to Umbraco Commerce as a ShippingRatesResult which contains a IEnumerable<ShippingRate> Rates property. A ShippingRate value for each carrier/service returned by the operator should be supplied. A ShippingRate consists of the following properties:

• Option - A ShippingOption instance, which consists of an Id and Name property for the given shipping service.

• PackageId - The ID of the package from the ShippingProviderContext that this rate is associated with.

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

The Calculation Process

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

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

Registering Dependencies

Unit of Work

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

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

Umbraco Commerce has two types of adjustments:

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

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.

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

Store Settings

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

General

Notification Settings

Order Settings

Product Settings

Gift Card Settings

Store Configuration

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

The available configuration options are:

• Locations - Defines different locations for a store.

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

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

Store Permissions

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

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

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

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

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

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

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

Setting Properties

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

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

System Properties

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

Order System Properties

Order Line System Properties

Automatic Properties

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

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

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

Product Uniqueness Properties

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

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

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

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

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

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

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

To add an item to the cart, configure Umbraco with a store and add the necessary properties for interaction. Learn more by following the .

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:

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

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

Example Payment Provider

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