In this article, we will review and compare Sitecore Experience Commerce customers and OrderCloud buyer users to facilitate developers looking to transition from XC to OrderCloud as well as identify a path for migration of existing XC solutions to OrderCloud.
We will look at a high-level comparison of architecture, functionality, and data models, with greater focus on transitioning from Sitecore Experience Commerce, meaning identifying a close path to parity in OrderCloud, using the Habitat catalog and SXA Storefront.
Customers
The Customer to Storefront Association
In an XC SXA implementation, customer accounts are registered under a security domain, which can be configured in the Content Editor on the /sitecore/Content/<tenant>/<site>/Settings/Site Grouping/<storefront> item.

Customers can only be registered to a single security domain and will not be accessible in storefronts configured to a different domain. A separate customer account would need to be created under the other security domains, but it would have no knowledge or relationship to accounts across domains. However, a security domain can be registered to multiple storefronts allowing a customer to share an account across storefronts.

In OrderCloud, customers can be represented as buyer users, which are registered under buyer companies, and can only belong to a single buyer company. This can be compared directly to the relationship between security domains and customers.
The relationship of a buyer to an OrderCloud storefront is not tightly coupled like the SXA storefront. Access to an OrderCloud storefront is managed through API clients, security profiles and their assignments to buyers. See Getting Started > Establishing API Access for more information.

The Customer to Catalog Association
Buyers also contain a DefaultCatalogID
property, which will create an associated catalog with an ID matching the buyer ID if not specified during the creation of a buyer. While it may seem like this limits Buyer A to a single catalog (Catalog A), multiple catalogs can be assigned via OrderCloud's catalog assignments, which matches XC's equivalent in supporting both Catalog A and Catalog C associations to Security Domain A via storefronts (figure 4).
The DefaultCatalogID
property will be utilised in certain APIs when a catalogID
is not supplied in their request, however is can be overridden. For now it is only important to understand that this is not a limiting factor in OrderCloud functionality for migration of data or functionality.

OrderCloud User Groups
OrderCloud also allows buyer users to be assigned to one or more buyer user groups, which can be used to supersede assignments to buyer users in bulk, e.g. provide access to special pricing for VIP buyer users.

Over in XC, a common customisation is an implementation of customer groups to assign customers in order to provide customer-group specific pricing, promotions, etc. While the implementation details may have the customer group represented as a separate custom entity or a property on a customer, conceptually both approaches achieve the same outcome (figure 6) and are on par with OrderCloud's architecture (figure 5), allowing a seamless transition path to OrderCloud.

Customer Addresses
In XC, customers have explicit addresses associations as the address component lives on the customer entity. The IsPrimary
flag is used to allow a default address selection in implementations.

In OrderCloud, addresses are separate objects that have an immediate association to the buyer, then with buyer address assignments addresses can have direct assignments to the buyer users or indirect assignments via buyer user groups.

To bring across customer addresses into OrderCloud figure 9 shows that we would simply create buyer addresses with buyer address assignments for the buyer user only, not the buyer user groups, as well as adding the IsPrimary
flag to the buyer address xp.

For buyer address assignments, there are two additional properties to consider, in IsShipping
and IsBilling
. These properties control whether the address can be assigned to an order as a shipping address or billing address respectively. As the SXA Storefront allows customer addresses to be used for both of these addresses, these flags on the buyer address assignments should be set to true
.
Data Mapping
With the conceptual analysis above, we will now review what data mapping would look like for migration and from a comparison standpoint.
In the XC Entity/Component column, components are assumed to live on the primary XC entity being mapped.
OrderCloud IDs do not allow spaces. It is important that the IDs are parsed to remove/replace invalid characters consistently.
Buyers
The DefaultCatalogID
property will be reviewed further during the catalog analysis article.
OC Property | Data Type | Required | XC Entity/Component | XC Property | Data Type | Notes |
---|---|---|---|---|---|---|
ID | string | No | Customer | Domain | string | |
Active | string | Yes | N/A | N/A | N/A | Set to true by default. |
Name | string | No | Customer | Domain | string | |
DefaultCatalogID | string | Yes | N/A | N/A | N/A | Assign to an existing catalog or PATCH later. |
xp | object | No | N/A | N/A | N/A | Any custom fields can be mapped to xp. |
Buyer Users
There are a few properties in OrderCloud are required while not mandatory in the SXA Storefront, so considerations for handling these properties will need to be made in these instances, e.g. applying fallback values.
OC Property | Data Type | Required | XC Entity/Component | XC Property | Data Type | Notes |
---|---|---|---|---|---|---|
buyerID | string | Yes | Customer | Domain | string | Is a resource parameter, not body property. |
ID | string | No | Customer | FriendlyId | string | |
Username | string | Yes | Customer | LoginName | string | |
Password | string | No | N/A | N/A | N/A | Password should not be migrated. |
FirstName | string | Yes | Customer | FirstName | string | Not a mandatory field in SXA, so a fallback value will need to be populated. |
LastName | string | Yes | Customer | LastName | string | Not a mandatory field in SXA, so a fallback value will need to be populated. |
string | Yes | Customer | string | |||
Phone | string | No | CustomerDetailsComponent | PhoneNumber | string | The XC PhoneNumber exists under an entity view of the CustomerDetailsComponent, so consider this a rough mapping. |
TermsAccepted | string | No | N/A | N/A | N/A | |
Active | boolean | Yes | Customer | AccountStatus | string | Set to true where AccountStatus == "ActiveAccount" |
xp | object | No | N/A | N/A | N/A | Any custom fields can be mapped to xp. |
Buyer Addresses
For buyer addresses, IDs need to be unique, therefore creating a convention to append the customer's FriendlyId
and the XC address' unique identifier, AddressName
, ensures there will be no conflicts.
OrderCloud only stores the ISO 3166-1 alpha-2 2-letter country code. Retrieving additional country details, such as country name, would best be handled by custom middleware, outside of OrderCloud.
OC Property | Data Type | Required | XC Entity/Component | XC Property | Data Type | Notes |
---|---|---|---|---|---|---|
buyerID | string | Yes | Customer | Domain | string | Is a resource parameter, not body property. |
ID | string | No | Customer AddressComponent | FriendlyId Party.AddressName | string | Using the convention <Customer.FriendlyId>_<Party.AddressName> will keep the address ID unique. |
FirstName | string | No | AddressComponent | FirstName | string | SXA Storefront does not capture FirstName. May wish to use Customer.FirstName instead. |
LastName | string | Yes | AddressComponent | LastName | string | SXA Storefront does not capture LastName. May wish to use Customer.LastName instead. |
Street1 | string | Yes | AddressComponent | Party.Address1 | string | |
Street2 | string | No | AddressComponent | Party.Address2 | string | |
City | string | Yes | AddressComponent | Party.City | string | |
State | string | Yes | AddressComponent | Party.StateCode | string | Can also use Party.State for full state name, depending on requirement. |
Zip | string | Yes | AddressComponent | Party.ZipPostalCode | string | |
Country | string | Yes | AddressComponent | Party.CountryCode | string | |
Phone | string | No | AddressComponent | Party.PhoneNumber | string | Will be empty in SXA Storefront default implementation. May wish to use Customer.[CustomerDetailsComponent].PhoneNumber instead. |
AddressName | string | No | AddressComponent | Party.AddressName | string | |
xp | object | No | N/A | N/A | N/A | Any custom fields can be mapped to xp. |
xp.IsPrimary | object | No | AddressComponent | Party.IsPrimary | boolean |
Buyer Address Assignments
Buyer address assignments are a straight forward mapping as per the table below.
OC Property | Data Type | Required | XC Entity/Component | XC Property | Data Type | Notes |
---|---|---|---|---|---|---|
buyerID | string | Yes | Customer | Domain | string | Is a resource parameter, not body property. |
AddressID | string | Yes | Customer AddressComponent | FriendlyId Party.AddressName | string | <Customer.FriendlyId>_<Party.AddressName> to keep the address ID unique |
UserID | string | No | Customer | FriendlyId | string | |
UserGroupID | string | No | N/A | N/A | N/A | |
IsShipping | string | No | N/A | N/A | N/A | Set to true . |
IsBilling | string | No | N/A | N/A | N/A | Set to true . |