This is the documentation for the Cart package for Umbraco Commerce.
Umbraco Commerce Cart is a free and open-source add-on package for Umbraco Commerce. It provides a low-code solution for creating an instant shopping cart in your Umbraco Commerce stores.
Umbraco Commerce Cart allows you to set up your shopping cart with minimal development costs.
A look at the Umbraco Commerce Cart UI
In this section, you will learn the key steps necessary to get started with the Cart package for Umbraco Commerce.
It is assumed that you already have an Umbraco website configured, Umbraco Commerce installed and a store set up. If you are not at this stage yet, read the core Umbraco Commerce documentation to learn how to get started.
Useful links
As well as the content in these documents, here are a few useful links to learn more about the Umbraco Commerce Cart package.
Installation
Detailed instructions on how to install and configure Cart into your Umbraco Commerce implementation.
The Cart package can be installed directly into your project's code base using NuGet packages.
NuGet Package Installation
To install the Umbraco Commerce Cart package via NuGet run the following command directly in the NuGet Manager Console window in Visual Studio:
PM> Install-Package Umbraco.Commerce.Cart
Client Assets Installation
Once installed, add the following CSS to your layout templates head section:
Add following JavaScript before the closing body tag:
Once installed, head to the section to configure the Cart for your solution.
Packages for Umbraco Commerce
Find detailed documentation for each of the official packages available for extending your Umbraco Commerce installation.
Below is an overview of the different add-ons that you can install into your Umbraco Commerce implementation. All add-ons are meant to extend the features and functionality already available in the core product.
Using These Docs
These docs are aimed at developers and users who have at least a basic understanding of Umbraco, as well as Umbraco backoffice principles.
As there is no code involved with using Umbraco Commerce Deploy, the docs are purely a series of articles covering how to install and configure Deploy.
Cart
Use this package to add a drop in cart solution to your Umbraco Commerce implementation.
Checkout
Use this package to add additional functionality to the checkout flow for your Umbraco Commerce implementation.
Portal
Use this package to add customer specific functionalities for your Umbraco Commerce implementation.
Deploy
This package is used to enable the use of Umbraco Deploy with your Umbraco Commerce implementation.
Product feeds
This plugin is a XML feed generator plugin which extracts product data from Umbraco node and generate structured XML feed.
Take a closer look at how the default checkout flow looks when installing the Checkout package for Umbraco Commerce.
Check out the screenshots below to see what you get with Umbraco Commerce Checkout straight out of the box.
Umbraco Commerce Checkout Settings
Umbraco Commerce Checkout Customer Details
Shipping methods
Payment methods
Order review
Order confirmation
Umbraco Commerce Checkout Order Email
Installation
Detailed instructions on how to install and configure Deploy into your Umbraco Commerce implementation.
The Umbraco Commerce Deploy package can be installed directly into your project's code base using our NuGet packages.
NuGet Package Installation
To install the Umbraco Commerce Deploy package via NuGet run the following command directly in the NuGet Manager Console window using Visual Studio:
PM> Install-Package Umbraco.Commerce.Deploy
Alternatively, you can also find and install the NuGet package via the NuGet Package Manager.
Upgrading
Umbraco Commerce Deploy does not consist of any UI files or database changes. It is generally ok to install the upgrade on top of a previous install.
Overview
This is the documentation for the Product Feed package for Umbraco Commerce.
After building up your commerce website, you can expand your product reach and show your products to a larger audience with product feeds. Umbraco Commerce Product Feed is a free and open-source add-on for Umbraco Commerce that helps you generate the XML files that are used in services like Google Merchant Center.
Umbraco Commerce Product Feeds package is an XML feed generator plugin that simplifies the creation of structured XML files. It automatically extracts product data from Umbraco nodes, organizes it according to standards and also allows you to add more information to the feed.
Current supported feed template:
Google Merchant Center
Overview
This is the documentation for the Checkout package for Umbraco Commerce.
Umbraco Commerce Checkout is a free and open-source add-on package for Umbraco Commerce. It provides a no-code solution for creating an instant checkout flow in your Umbraco Commerce stores.
Umbraco Commerce Checkout allows you to set up your checkout flow with minimal configuration.
In this section, we will guide you through the key steps necessary to get you started with the Checkout package for Umbraco Commerce.
It is assumed that before we begin that you already have an Umbraco website configured and Umbraco Commerce installed and a store set up. If you are not at this stage yet, read the to learn how to get started.
Customize Portal
This documentation shows how to customize the Portal package for Umbraco Commerce.
The Portal is designed with flexibility in mind, offering multiple customization options to ensure it fits seamlessly with your specific Commerce workflow.
The portal includes customizable pages (such as login, registration, and account management) that can be aligned with your brand.
Setup
To customize the Portal, you must first override the existing files for the step you want to modify.
Deploying Changes
Learn more about the advantages of using the Umbraco Commerce Deploy package with Umbraco Commerce.
After installing Umbraco Commerce Deploy, it will automatically serialize any changes made in the Umbraco Commerce settings section to disk. They will be added to the data\revision folder alongside Umbraco's own serialized content.
These files should be committed to your repository. Umbraco Deploy will then monitor these files and automatically deploy changes between environments for you.
Learn more about how the deployment process works in the .
Extending the plugin
Learn how to extend the plugin by adding a custom property value extractor.
In this article, you can find an example of extending the plugin by adding a custom property value extractor.
Add a custom property value extractor
When a default property value extractor does not suit your need, you can create your own extractor to extract the property value yourself.
For example, when a product's stock value is 0
Overview
This is the documentation for the Deploy package for Umbraco Commerce.
Umbraco Commerce Deploy is a free and open-source add-on package for Umbraco Commerce. It provides Umbraco Deploy and Umbraco Cloud support, allowing the transfer of Umbraco Commerce settings between environments.
In this section, we will guide you through the key steps necessary to get you started with the Deploy package for Umbraco Commerce.
It is assumed that you already have one of the following setups:
A Umbraco Cloud site with Umbraco Commerce installed and configured.
Customize Email Templates
This documentation shows how to customize the Portal email templates.
The Portal includes customizable email templates for account confirmation and password reset, which can be updated to match your site’s design.
Setup
To allow customization you must first 'override' the existing template files for the step required to be modified.
To do this follow these steps:
Screenshots
Take a closer look at the default customer portal available when installing the Portal package for Umbraco Commerce.
Check out the screenshots below to see what you get with Umbraco Commerce Portal straight out of the box.
Portal Settings
feed template.
In this section, we will guide you through the key steps necessary to get you started with the Product Feeds package for Umbraco Commerce.
It is assumed that before we begin you already have an Umbraco website configured and Umbraco Commerce installed and a store set up. If you are not at this stage yet, read the core Umbraco Commerce documentation to learn how to get started.
A look at how the default Checkout flow appear on the frontend.
Ignoring Settings
Some entities in Umbraco Commerce accept configuration settings such as Payment Methods, Shipping Methods, and Tax Calculation Methods. These settings can be environment-specific, and therefore, you may not want to deploy them between environments. To prevent this from happening, you can add the following configuration options to your appsettings.json file.
For each supported entity type, you can supply an IgnoreSettings option, which contains an array of aliases of the settings options to be ignored.
You can often create a new implementation of ISingleValuePropertyExtractor or rarely IMultipleValuePropertyExtractor.
This plugin uses Collection Builder pattern which is commonly used in Umbraco. You can use these two extension methods during application initialization to add your value extractors.
Afterwards, your extractor name should show up in the dropdown under Property And Node Mapping section.
Add them to Views/UmbracoCommercePortal in your project directory. It might be necessary to create the folder first.
Make a small text change to one of the Views to verify that the files are in use.
Verify that the changes are carried out and displayed correctly.
You are now ready to start customizing the Portal email templates to fit the design of your website.
If you want to use your own email template views, ensure that they are using the EmailModel. Next, go to the Templates | EmailTemplates settings in your store. For each Umbraco Commerce Portal template, update the path to point to your custom view.
Overview of the store's email templates settings
Overview of the properties of an email template
Useful links
Here are a few useful links to learn more about the Umbraco Commerce Portal package:
Learn how to configure Umbraco in order to start using the Portal package.
After installing the Portal package, a series of content nodes will be created for you on your site.
At the root of these nodes, you can configure options for your customer portal.
Step 1: Configuring the Portal
Overview of some of the different configuration options for customizing the Portal.
In Umbraco Commerce 16.1.0, the logo and theme color options have been moved to the store Settings section for consistent theming across add-ons.
Name
Description
Overview
Documentation for the Customer Portal package for Umbraco Commerce.
Umbraco Commerce Portal is a free and open-source add-on package for Umbraco Commerce. It provides a no-code solution for creating a customer portal. Users can log in, manage profiles, and view order history for their Umbraco Commerce stores.
A look at how the default My Account page of the Customer Portal looks on the frontend
A look at how the default Order History page of the Customer Portal looks on the frontend
This section guides you through the key steps necessary to get started with the Portal package for Umbraco Commerce.
Before beginning, ensure you already have an Umbraco website configured, Umbraco Commerce installed, and a store set up. If you are not at this stage yet, see the Umbraco Commerce documentation to learn how to get started.
Useful links
As well as the content in this documentation, here are a few useful links to learn more about the Umbraco Commerce Portal package itself.
Customize Checkout
This documentation shows how to customize the Checkout package for Umbraco Commerce.
It is assumed that you already have an Umbraco website configured Umbraco Commerce installed and a store set up. If you are not at this stage yet, read the core Umbraco Commerce documentation to learn how to get started.
Umbraco Commerce Checkout is a free and open-source add-on package for Umbraco Commerce. It is possible to amend the default behavior to customize the checkout to your needs.
Setup
To allow customization you must first 'override' the existing files for the step required to be modified.
To do this follow these steps:
Copy the equivalent .
Add them to Views/UmbracoCommerceCheckout in your project directory. It might be necessary to create the folder first.
Make a small text change to one of the Views to verify that the files are in use.
You are now ready to start customizing the Checkout page to fit the design of your website.
Useful links
Here are a few useful links to learn more about the Umbraco Commerce Checkout package:
Installation
Detailed instructions on how to install and configure Portal into your Umbraco Commerce implementation.
The Portal package can be installed directly into your project's code base using NuGet packages.
NuGet Package Installation
To install the Umbraco Commerce Portal package via NuGet run the following command directly in the NuGet Manager Console window in Visual Studio:
Alternatively, you can also find and install the NuGet package via the NuGet Package Manager.
Content Installation
When the Portal package is installed, all relevant database configurations automatically occur via Umbraco Migrations. There are a series of content creation steps that need to be triggered manually as these types of migrations are not supported by Umbraco.
To install the relevant Portal content follow these steps:
Access the Umbraco CMS backoffice.
Navigate to the Settings section.
Locate the Portal Dashboard.
Click the Install button.
Select your site's root node which is configured with a Umbraco Commerce store.
Click Install.
During this install, Umbraco Commerce Portal will perform the following tasks:
Upgrading
Before upgrading, it is always advisable to take a complete backup of your site/database.
The Portal package uses a combination of database migrations and a manual install dashboard for both installs and upgrades. To upgrade, install the latest version over the existing package and complete the installation steps.
Installation
Detailed instructions on how to install and configure Product Feeds into your Umbraco Commerce implementation.
The Product Feeds package can be installed directly into your project's code base using NuGet packages.
Getting started
Below you can find some steps on installing the package using NuGet and getting started with implementing the Product Feeds into your Umbraco Commerce store.
Installation
Detailed instructions on how to install and configure Checkout into your Umbraco Commerce implementation.
The Checkout package can be installed directly into your project's code base using NuGet packages.
NuGet Package Installation
To install the Umbraco Commerce Checkout package via NuGet run the following command directly in the NuGet Manager Console window in Visual Studio:
Alternatively, you can also find and install the NuGet package via the NuGet Package Manager.
Configure Umbraco
Learn how to configure Umbraco in order to start using the Checkout package.
After installing the Checkout package, a series of content nodes will be created for you on your site. These will control the checkout flow.
On the root of these nodes, you can configure a series of options to customize the checkout flow to your needs.
Step 1: Configuring the Checkout flow
PM> Install-Package Umbraco.Commerce.Portal
Verify that the changes are carried out and displayed correctly.
Locate where you register the dependenciesIUmbracoBuilder.AddUmbracoCommerce() and add a call to IUmbracoCommerceBuilder.AddCommerceProductFeeds() to add this plugin to your website.
Open your store's setting page in the backoffice.
Click on Product Feed section.
product feed list page
Click on Create Product Feed button and fill in the feed settings. Mandatory fields are marked with a red asterisk (*). You can add more product data by adding new mappings in Property And Node Mapping section.
feed setting page
After saving the feed setting, a link to access the feed will show up under Feed URL Segment field and at the bottom of the page.
open feed link
Google Merchant Center Feed sample:
google merchant center feed
Upgrading
Even though the package modifies only the umbracoCommerceProductFeedSetting table, it is always advisable to take a complete backup of your site/database before upgrading.
The Product Feeds package uses a database migration for both installs and upgrades. Upgrading is generally a case of installing the latest version via NuGet over the existing package and restarting the website.
Installing Umbraco Commerce Checkout via the NuGet Package Manager.
Content Installation
When the Checkout package is installed, all relevant database configurations automatically occur via Umbraco Migrations. There are a series of content creation steps that need to be triggered manually as these types of migrations are not supported by Umbraco.
To install the relevant Checkout content follow these steps:
Access the Umbraco CMS backoffice.
Navigate to the Settings section.
Locate the Checkout Dashboard.
The Checkout Dashboard in the Settings section of the Umbraco backoffice.
Click the Install button.
Select your site's root node which is configured with a Umbraco Commerce store.
Click Install.
The dialog that appears when installing content through the Checkout dashboard.
During this install, Umbraco Commerce checkout will perform the following tasks:
Upgrading
Before upgrading, it is always advisable to take a complete backup of your site/database.
The Checkout package uses a combination of database migrations and a manual install dashboard for both installs and upgrades. Upgrading is generally a case of installing the latest version over the existing package and running through the installation steps.
In Umbraco Commerce 16.1.0, the logo and theme color options have been moved to the store Settings section for consistent theming across all add-ons.
Name
Description
Collect Shipping Info
A checkbox to set whether to collect shipping info or not. If deselected, all shipping info-related fields/steps will be removed from the checkout flow
Order Line Property Aliases
A comma-separated list of order line property aliases to display in the order summary.
Checkout Back Page
The page to go back to when backing out of the checkout flow.
Terms and Conditions Page
Defines which page on the site contains the terms and conditions of the store.
Privacy Policy Page
The page on the site containing the privacy policy.
Hide from Navigation
Checkbox to hide the checkout page from the site's main navigation.
In addition to these root node settings, each checkout step page also has a number of configurable options:
Name
Description
Short Step Name
A short name for this step to display in the checkout navigation.
Step Type
The checkout step to display for this step of the checkout flow.
Linking to the Checkout
With the checkout setup and configured the final step is to configure your cart page to link through to the checkout flow. How you do this is up to you:
Link to the URL /checkout or
Use a Content Picker to select the checkout node to link to.
Overview of some of the different configuration options for customizing the Checkout flow.
Configuration
Learn how to configure the Umbraco Commerce Cart package.
The Cart package is configured using a JavaScript, CSS, and data attributes-based API.
Initialization
Before adding items to a cart, it is required that the Cart package is initialized with some default settings. This is done using the UCC.init global function which should be executed after the umbraco-commerce-cart.js file is loaded.
umbracoBuilder.AddUmbracoCommerce(ucBuilder => {
ucBuilder.AddCommerceProductFeeds(); // add this line
}
PM> Install-Package Umbraco.Commerce.Checkout
Require Login
Checkbox to require customers to log in before proceeding to checkout.
Login Page
Defines the page on the site used for logging in when login is required before checkout.
The core initialization settings are shown in the table below.
Key
Description
store
The ID or alias of the store the cart should be associated with.
checkoutUrl
The URL of the checkout page the cart should redirect to on checkout.
showPricesIncludingTax
Define whether to show prices inclusive or exclusive of sales tax. Defaults to false.
Calling the init method will also automatically bind any UI elements configured using the following APIs.
UI Elements
Add to Cart Buttons
With Umbraco Commerce Cart, products that can be added to a cart are defined by adding attributes to HTML elements on your site. Most likely this will be a "buy" <button> element, however, any HTML element can become an add-to-cart component.
The first step when defining an add-to-cart component is to add the ucc-add-to-cart class to the element. This informs Umbraco Commerce Cart that it should react to that element's click event.
Along with the ucc-add-to-cart class, a series of data attributes provides information about the product being added to the cart. At a minimum, a data-ucc-product-reference is required, but the following table outlines all the available configuration options.
Key
Description
data-ucc-product-reference
The unique reference for the product being added. This is usually the Key of the product Umbraco node.
data-ucc-product-variant-reference
The unique reference for a variant of the primary product being added. This is usually either a child variant node Key or the Key of a complex variant item from the Variants property editor.
data-ucc-quantity
The amount of the given product to be added.
data-ucc-property1-key
The key of a property to set on the added order line.
data-ucc-property1-value
The value of a property to set on the added order line.
data-ucc-bundle-reference
A unique reference to use to mark this item as a bundle.
Some attributes end with a number. This signifies that the attribute defines a collection and so multiple attributes can be defined with each distinct combination incrementing the number by 1. It is important that these attributes start from 1 and must be sequential without gaps.
With an add-to-cart button defined, clicking on the button will automatically add the product and open the cart for display.
Shopping cart modal.
Open Cart Button
While the cart will open automatically when an item is added, you can also enable the customers to open their carts manually. To do this, add a ucc-cart class to a link or button element. The Umbraco Commerce Cart will then automatically bind a click event handler to trigger opening the cart.
Cart Count Label
Another common feature on commerce sites is the ability to display the total number of items in the current cart. To do this, define an HTML element with a ucc-cart-count class applied. Umbraco Commerce Cart will then automatically update its text value whenever the cart changes.
Commands
As well as the automatic API defined above, it is possible to trigger Umbraco Commerce Cart commands manually via a number of JavaScript functions.
Localization
The cart UI supports being translated into any language. Out of the box, it comes with a default English translation, but additional locales can be configured.
Localization is controlled via the lang attribute in the <html> tag of your site.
In the above example, Umbraco Commerce Cart will look for a French locale. If a given locale can't be found, then it will default back to English.
Additional locales can be added either via the UCC.init method or by calling the UCC.addLocale command.
The default English locale has the following values and defines the required keys for a locale.
To override a locale you can re-add it by reusing the same language key.
Displaying Properties
If you capture any custom properties, you may want to display them within the cart. Displaying properties is achieved in two steps.
First, you define the property keys you wish to display either via the UCC.init command, or the UCC.showProperty command.
Next, you define a localization key to use as a label for each property.
Now, when the cart is displayed, the defined properties will be displayed using the localization value as their label.
Example property
Theming
To allow customization of the cart UI, CSS variables are used to allow overriding of the default styles.
The following details the default values, and the available keys to override.
Styles can be overridden by including a stylesheet after the Umbraco Commerce Cart stylesheet, replacing the desired keys.
Error Handling
By default, Umbraco Commerce Cart will log any request errors to the console. If you would like to display errors to your users or handle them differently you can provide an error handler function.
// Open the cart
UCC.openCart();
// Close the cart
UCC.closeCart();
// Re-bind UI API elements
UCC.bind();
// Update the store configuration
UCC.setStore('brewed');
// Update the checkout URL
UCC.setCheckoutUrl('/new-checkout');
// Set whether to display prices inclusive or exclusive of sales tax
UCC.showPricesIncludingTax(true);
// Show a property in the cart
UCC.showProperty('myProp');
// Change the language of the cart UI
UCC.setLang('dk');
// Add or replace a localization dictionary
UCC.addLocale('en', {
key: 'value',
...
});
// Set the error handler
UCC.setOnError(msg => {
console.log(msg);
});
