Transitioning from Sitecore Experience Commerce to OrderCloud: Customers to Buyer Users

Reading Time: 6 minutes

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.


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.

Figure 1: An example domain configuration for a storefront.

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.

Figure 2: XC Security Domains have a zero to many relationship with 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.

Figure 3: The basic structure comparison between customers to users.

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.

Figure 4: XC relationship between customers and catalogs vs. OrderCloud’s relationship between buyer users and catalogs.

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.

Figure 5: OrderCloud can group buyer users in buyer user groups.

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.

Figure 6: Customer groups are a common customisation in XC, which can be thought of in a simliar respect to OrderCloud’s buyer user groups, however it is not part of the default ecosystem.

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.

Figure 7: Customer addresses in XC.

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.

Figure 8: Buyer address architecture in OrderCloud.

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.

Figure 9: OrderCloud’s representation of XC customer structure.

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.


The DefaultCatalogID property will be reviewed further during the catalog analysis article.

OC PropertyData TypeRequiredXC Entity/ComponentXC PropertyData TypeNotes
ActivestringYesN/AN/AN/ASet to true by default.
DefaultCatalogIDstringYesN/AN/AN/AAssign to an existing catalog or PATCH later.
xpobjectNoN/AN/AN/AAny 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 PropertyData TypeRequiredXC Entity/ComponentXC PropertyData TypeNotes
buyerIDstringYesCustomerDomainstringIs a resource parameter, not body property.
PasswordstringNoN/AN/AN/APassword should not be migrated.
FirstNamestringYesCustomerFirstNamestringNot a mandatory field in SXA, so a fallback value will need to be populated.
LastNamestringYesCustomerLastNamestringNot a mandatory field in SXA, so a fallback value will need to be populated.
PhonestringNoCustomerDetailsComponentPhoneNumberstringThe XC PhoneNumber exists under an entity view of the CustomerDetailsComponent, so consider this a rough mapping.
ActivebooleanYesCustomerAccountStatusstringSet to true where AccountStatus == "ActiveAccount"
xpobjectNoN/AN/AN/AAny 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 PropertyData TypeRequiredXC Entity/ComponentXC PropertyData TypeNotes
buyerIDstringYesCustomerDomainstringIs a resource parameter, not body property.
stringUsing the convention <Customer.FriendlyId>_<Party.AddressName> will keep the address ID unique.
FirstNamestringNoAddressComponentFirstNamestringSXA Storefront does not capture FirstName. May wish to use Customer.FirstName instead.
LastNamestringYesAddressComponentLastNamestringSXA Storefront does not capture LastName. May wish to use Customer.LastName instead.
StatestringYesAddressComponentParty.StateCodestringCan also use Party.State for full state name, depending on requirement.
PhonestringNoAddressComponentParty.PhoneNumberstringWill be empty in SXA Storefront default implementation. May wish to use Customer.[CustomerDetailsComponent].PhoneNumber instead.
xpobjectNoN/AN/AN/AAny custom fields can be mapped to xp.

Buyer Address Assignments

Buyer address assignments are a straight forward mapping as per the table below.

OC PropertyData TypeRequiredXC Entity/ComponentXC PropertyData TypeNotes
buyerIDstringYesCustomerDomainstringIs a resource parameter, not body property.
string<Customer.FriendlyId>_<Party.AddressName> to keep the address ID unique
IsShippingstringNoN/AN/AN/ASet to true.
IsBillingstringNoN/AN/AN/ASet to true.