Sitecore XC software architecture

Current version: 10.3

The Sitecore Experience Commerce (XC) solution uses a combination of architectural entities to achieve configuration, scalability, and extensibility.


The Commerce Engine plugins deliver all commerce functionality in the Sitecore XC solution, including Commerce Engine policies, the elements of Commerce plugins that you can configure to control aspects of Commerce Engine functionality and behavior.

Sitecore XC exposes policies for configuration in JSON files. You can change the configuration by editing the relevant environment policy file.

Sitecore XC stores all policies and configurations that govern Commerce Engine behavior in the Global database, the centralized Commerce policy store. Policies are persisted in the Global database using the bootstrapping process. Policies are heavily cached and rarely change their values outside of deployment scenarios.


Sitecore Experience Commerce uses the concept of environments to allow for different Commerce Engine configurations. In the Commerce Engine, an environment defines a collection of policies that determines how the Commerce Engine behaves, and the dataset that it works with. When a client makes a call to the Commerce Engine, the call header specifies the targeted environment, allowing the Commerce Engine to respond to the request in the context of that environment configuration.

Commerce environments provide the flexibility to have separately configurable pools of data and service functionality running as distinct Commerce Engine environments that you can tailor to the requirements of the calling client, and scale according to the demand of your deployment. You can configure multiple Commerce environments on a single Commerce Engine service instance, or distribute environments over multiple instances of Commerce Engine services, either on the same server, or across servers for a scaled deployment.

A Commerce environment is a core commerce entity class (Sitecore.Commerce.Core.CommerceEnvironment) that contains:

  • A collection of policies affecting how the system behaves in response to Commerce Engine calls.

  • An artifact store ID that corresponds to a Commerce dataset.

When a client makes a call to the Commerce Engine, it specifies the name of the Commerce environment in the call header. The environment name allows the Commerce Engine to respond with the behavior and dataset expected by the client.

The ArtifactStoreID property and the environment "Name" property in the Plugin.Habitat.CommerceAuthoring.json file.

You can create your own environment and customize the configuration as required.


Bootstrapping is the process of loading the policy and environment data from JSON files on disk created during deployment into the Global database, so that other Commerce Engines can access it.

After bootstrapping, the Commerce Engine no longer needs the environment JSON files, because it retrieves any subsequent environment configuration directly from the database during normal runtime operations. However, if you make any subsequent changes to the environment JSON files, you must bootstrap the Commerce Engine again to make sure the changes are propagated to the Global database.

Commerce Engine roles

The Sitecore XC solution implements the concept of Commerce Engine roles to support scalability. Commerce Engine roles are deployed instances of core Commerce processing, each serving distinct logical roles. The distinction between roles is purely logical as there is no real difference in the deployed bits between different installed roles. The distinction between the roles is defined by where the traffic originates from, and the configuration of the Commerce environment that is being called.

When a client makes a call to the Commerce Engine, it must specify the target Commerce environment in the call's header. It is the configuration of the target environment that determines how the Commerce Engine behavior handles the request, in the context of the environment specified in the request header.

Commerce Engine roles can coexist on the same server, or be located on separate servers. You can scale them independently as required.

In a production environment, traffic is usually split up among multiple installed instances of the Commerce Engine, which are usually physically located close to their traffic sources, as shown in this reference architecture diagram.

The use of distinct Commerce Engine instances for different environments allows explicit independent control of functions for each deployed role, such as caching, data storage, integration connections, and so on.

The sample Sitecore XC solution defines three instances of the Commerce Engine, each representing a role:

Table 1. 




The Authoring role is the instance of the Commerce Engine that serves traffic from the Business Tools. Since this role serves lighter traffic (because e-commerce solutions have relatively few business users compared to the number of shoppers), scaling requirements are normally relatively low.


Starting with Sitecore XC 10.2, the default XC deployment does not create a distinct Commerce Engine service instance dedicated to DevOps operations. Instead, the Authoring Commerce Engine role also serves as the target environment for your DevOps operations (such as bootstrapping, environment initialization functions, and other CommerceOps API request).


The Shops role is the instance of the Commerce Engine that serves traffic from one or more storefronts. Requests from the storefront are handled by Commerce Connect and Commerce Engine Connect. This content delivery role can scale to support demand, and is usually installed in close proximity to the Sitecore XP instances that generate the traffic.


The Minions role is an instance of the Commerce Engine that runs independently and supports asynchronous processing (including any post-order capture processing as well as any cleanup). The Minions role is usually set up as a worker role (not a web role) and does not receive any web traffic. This role contains a series of minions, each one with a specific task (for example, a pending order minion that is used to process the pending orders queue).


A Commerce solution must only have a one instance of the Commerce Engine running the Minions role. Running multiple Minion roles on multiple instances of the Commerce Engine causes concurrency errors.


Sitecore XC uses the following Commerce databases:

  • The Shared Environments database (SitecoreCommerce_SharedEnvironments) that stores all Commerce datasets.

  • The Global database that stores Commerce Engine environment configurations.

  • The Archive database that stores archived Commerce entities, such as old journal entries and inactive orders, when enabled.

Commerce Shared Environments database

The Commerce Shared Environments database stores all commerce business data, for example, catalog data, customer records, pricing information, configured promotions. In addition to business data, the Shared Environments database also stores the generic entities and lists that power core commerce functionality provided by the various plugins.

Commerce entities that are part of the same business dataset share a common artifact store ID value. For example, in the default Shared Environment database, all Commerce entities that are part of the Habitat dataset are stored against the same artifact store ID value. Entities that are part of the Adventure Works dataset are stored against a different artifact store ID. The following shows an example of the sitecore_commerce_storage.CatalogEntity table, where entities are stored against different artefact store ID values.

Commerce entities with different Artefact store ID value based on dataset.

When a client makes a request for Commerce data, the environment ID specified in the call request corresponds to the artifact store ID that is configured in the Commerce environment file. The artifact store ID is generated during the data initialization process. In the Shared Environments database, all Commerce entities that belong to the same Commerce dataset share the same artifact store ID value.


Commerce entities such as sellable items are not moved to the Sitecore Web database for publishing on the storefront, as shown in this reference architecture diagram. Commerce data remains in the Shared Environments database whether or not items are published to the storefront. For Commerce entities, publishing to the Storefront is a function of the "published" property value (bool.) that is set against an entity, for example, as an outcome of the publishing workflow in the Business Tools.

Global database

The Global database stores all Commerce Engine environment configurations data that governs how the Commerce Engine behaves in response to requests initiated by a client for a specified Commerce environment.

The bootstrap process is responsible for registering the environment configuration and policy data in the Global database.


The Commerce Engine includes a pluggable framework for extending or modifying existing functionality. The Sitecore XC plugin architecture provides extensibility points for custom functionality, without compromising upgradeability.

This plugin architecture allows for opt-in complexity and progressive enhancement of your Sitecore XC solution. You can write plugins for connectors to integrate third-party systems. You can also write plugins to extend business logic, or to extend the Business Tools.

Do you have some feedback for us?

If you have suggestions for improving this article,