data-migration – Andrew Sutherland's Blog

March 31, 2022January 10, 2023

Transitioning from Sitecore Experience Commerce to OrderCloud: Carts to Unsubmitted Orders and Carts

Reading Time: 11 minutes

In this article, we will review and compare Sitecore Experience Commerce carts and OrderCloud unsubmitted orders 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.

Conceptual Architecture and Features

Carts vs Unsubmitted Orders and Carts

Architecture Overview

In XC, the cart entity stores information about the order to be placed. When an order is placed, the contents of a cart is copied over into a new order entity with an initial order status of Pending.

OrderCloud has two approaches in handling the cart/order lifecycle. The solution can leverage unsubmitted orders or the OrderCloud’s cart resource.

Unsubmitted Orders

In OrderCloud, an order represents both the cart and order within the cart/order lifecycle, using the Status property to identify its current state. The initial status of the order is Unsubmitted, which is effectively the XC cart equivalent. When the order is submitted, the order will then transition its status to Open, matching the XC order with status of Pending.

It is also possible that the OrderCloud order submitted status will be set to AwaitingApproval, however this status is not relevant for the SXA storefront comparison.

Figure 1: The XC and OrderCloud representations of a shopping cart being constructed and their initial state once the order has been submitted.

Referencing figure 2, there are a few important details regarding the XC and SXA cart to order architecture in relation to OrderCloud’s architecture:

SXA sees that a customer only interacts with a single cart per storefront, by using the naming convention, “Default<customer id><storefront name>“, to identify the cart id and is the only means of a relationship that the customer has with the cart in the XC database.
The Commerce Engine’s /carts endpoint, which retrieves the cart, requires the cartId parameter and does not have consideration for the user context.
While order ids must be unique, orders are created with randomly generated ids and are not copied from the cart’s fixed id. Orders are persisted, accompanied with a list entry, which represent the relationship between the customer and the orders they have placed.
During order creation, after the cart contents has been copied to the order, the cart is emptied to allow it to be used for subsequent order placement.

In comparison to OrderCloud’s architecture, orders are tightly coupled to their owners via the FromUserID property, and as both order ids in XC and OrderCloud are generated, there is no chance for Id conflicts.

In managing a single order, the most recent unsubmitted order is considered the active ‘cart’ and as such does not need to rely on an order id to identify the cart as its relationship to the user as it’s tightly coupled to the owner via the FromUserID property.
The /me/orders endpoint retrieves the order based on user context, which is extracted from the auth token, rather than the order id.
The order id is also generated by default, so there’s no chance of an ID conflict when allowing the platform to generate it.
There is no implementation concerns around migrating a cart to an order.

Figure 2: The SXA storefront will use a single cart per customer, which is converted into each order, whereas OrderCloud creates the orders directly allowing multiple unsubmitted orders being active simultaneously.

OrderCloud Carts

As an alternate approach to tracking and utilising the unsubmitted orders in an implementation, OrderCloud also provides a cart resource, which can simplify the implementation as it behaves much the same as the orders resource without the need for identifying, persisting, and passing the order ID for requests. Instead, the cart resource will point to the latest unsubmitted orders or create a new order if no unsubmitted orders exist for the user. When the cart is submitted, the next unsubmitted order, if available, will become the active cart.

More information can be found in Introducing the Cart API.

Choosing Between Orders and Cart Implementations

When deciding whether to use the orders or cart resource in an implementation, the cart resource will typically be the preferred implementation practice for the majority of storefronts as it can handle a single cart or multiple carts for profiled users, allowing the implementation to switch the order context for the user.

For marketplaces requiring multiple storefronts, e.g. a storefront per brand or storefront per country, where user accounts are shared across storefronts, the orders resource allows the storefront to control the order context for each user as seen in figure 4.

Figure 3: In a multi-storefront, shared user scenario, the cart resource’s order context is dependent on the user.

Figure 4: In a multi-storefront, shared user scenario, the order resource allows the implementation to control the order context.

Storefront User Journey

In figure 5, we see a high-level user journey for the SXA storefront alongside the OrderCloud equivalent. While OrderCloud’s user journey appears to be longer, this is only due to order requiring explicit creation and XC consolidating shipping address and shipping method into fulfillment details, and billing address and payment into payment details. Ultimately, the user journey is matched and there are no sacrifices necessary.

Figure 5: Cart to order vs unsubmitted order to submitted order user journey comparison.

Viewing the Cart/Order

In XC, the GET /Carts({cartId}) endpoint is typically called with the $expand query parameter to retrieve all cart components, cart lines and their components for the full view of the cart.

In OrderCloud, the RESTful API provides individual endpoints for extracting order data at more granular levels. For example the order details can be retrieved via the GET /orders/{direction}/{orderID} or GET /cart endpoint, but it won’t provide the line item details, which can be retrieved in bulk using GET /orders/{direction}/{orderID}/lineitems or GET /cart/lineitems, or individually via GET /orders/{direction}/{orderID}/lineitems/{lineitemID} or GET /cart/lineitems/{lineitemID}.

Alternately, OrderCloud also provides GET /orders/{direction}/{orderID}/worksheet and GET /cart/worksheet endpoints, which return the order object along with all line items and all responses from integration events. providing a more complete view, however some objects such as price schedule details will still require additional requests from the appropriate resources, which are typically only retrieved on demand as required.

Cart vs Order Totals

In the table below, we see a comparison between the cart line totals side by side with the equivalent line item totals. The notable differences are as follows:

XC Adjustments may include taxes, fulfillment fees, and promotion discounts, whereas OrderCloud breaks out the each adjustment classification at the order level.
As calculations with adjustments are calculated differently at the line-level and cart/order level, calculating the GrandTotal/Total may result in differently between the platforms.
The PaymentsTotal is not available on the order, however the payments total can be retrieved and calculated by the middleware, using OrderCloud’s GET /orders/{direction}/{orderID}/payments or GET /cart/payments endpoint.

Cart (XC)	Calculation	Order (OC)	Calculation	Match
`SubTotal`	Sum of all line-level `SubTotal`s.	`Subtotal`	Sum of all LineItem.LineSubtotals.	Yes
`AdjustmentsTotal`	Sum of all cart-level `Adjustments`.	`ShippingCost`	Handled by middleware via OrderCalculate integration event.	No
		`TaxCost`	Handled by middleware via OrderCalculate integration event.	No
		`PromotionDiscount`	Sum of all order-level and line item-level promotion discount amounts applied.	No
`GrandTotal`	`SubTotal` + sum of all cart-level adjustments flagged with `IncludeInGrandTotal` being `true` + sum of all line-level `AdjustmentsTotal`s	`Total`	`Subtotal` + `TaxCost` + `ShippingCost` – `PromotionDiscount`.	No
`PaymentsTotal`	Sum of all `PaymentComponent` Amounts.			N/A

Cart Lines vs Line Items

Adding a Cart Line vs Line Item

From an API perspective, to add a cart lines in XC, the request requires the cartId, quantity, and itemId, consisting of catalogId, sellableItemId, and variationId.

The catalogId is intended to resolve pricing and promotions for sellable items and their variants, based on the catalog associations to price books and promotion books as per the XC architecture.

POST https://authoring.engine.dev/api/AddCartLine HTTP/1.1

{
  "cartId": "{orderId}",
  "itemId": "{catalogId}|{sellableItemId}|{variantId}",
  "quantity": 1
}

Adding a line item in OrderCloud is much the same as seen in the example request below. orderId parameter replaces the cartId, while the ProductId equates to the sellableItemId. The catalogId however, is not required as pricing and promotions are not dependent on catalog assignments, and rather than passing the variantId, the individual product specs with OptionIDs are specified, ultimately resolving to variant equivalent, but also caters for specialised open text specs that OrderCloud supports.

POST https://sandboxapi.ordercloud.io/v1/orders/outgoing/{orderId}/lineitems HTTP/1.1

{
  "ProductID": "{productId}",
  "Specs": [
    {
      "SpecID": "{specId}",
      "OptionID": "{specOptionId}"
    },
    {
      "SpecID": "{specId2}",
      "OptionID": "{specOptionId2}"
    }
  ]
}

Cart Line Rollup

In the SXA storefront, when adding a sellable item/variation to the cart that has already been added, the quantity will be updated to reflect the initial cart’s quantity plus the quantity added. This is known as cart line rollup and is controlled by the RollupCartLinesPolicy.Rollup property in the Commerce Engine’s environment role configuration.

As line rollup is not a native feature of OrderCloud’s RESTful API, this functionality could be implemented in the middleware. Instead adding line items will create a new line item in the order, in the same manner that XC will with rollup disabled.

Figure 7: Create line item functionality.

Line-Level Pricing

XC’s cart lines contain the UnitListPrice and the SellPrice on the PurchaseOptionMoneyPolicy, which can be thought of as “was” and “now” pricing respectively.

The SellPrice can evaluate to the same value as the UnitListPrice, to which the SXA storefront will treat this as a standard price.

"Policies": [
    {
        "@odata.type": "#Sitecore.Commerce.Plugin.Pricing.PurchaseOptionMoneyPolicy",
        "PolicyId": "5e6c1f42c7c94bc4b79696e716b6cda5",
        "Models": [],
        "Expires": "2019-04-22T13:13:18.8117816Z",
        "SellPrice": {
            "CurrencyCode": "USD",
            "Amount": 6
        },
        "FixedSellPrice": false
    }
],
"UnitListPrice": {
    "CurrencyCode": "USD",
    "Amount": 2429.99
}

The MessagesComponent, also shows the audit trail detailing how the cart line’s unit list price and sell price were resolved, which are evaluated from ListPrices and Price Card Snapshots at the sellable item and item variation levels.

Cart Line MessageComponent Snippet

{
	"@odata.type": "#Sitecore.Commerce.Core.MessagesComponent",
	"Id": "7e6bc27965ef4f3a954e6fcdadb96fa5",
	"Name": "",
	"Comments": "",
	"Policies": [],
	"Messages": [
		{
			"Code": "Pricing",
			"Text": "SellPrice<=PriceCard.Snapshot: Price=$10.00|Qty=1.0|PriceCard=Habitat_PriceCard"
		},
		{
			"Code": "Pricing",
			"Text": "ListPrice<=PricingPolicy: Price=$1,919.69"
		},
		{
			"Code": "Pricing",
			"Text": "Variation.SellPrice<=Variation.PriceCard.Snapshot: Price=$9.00|Qty=1.0|Variation=56042567|PriceCard=Habitat_VariantsPriceCard"
		},
		{
			"Code": "Pricing",
			"Text": "Variation.ListPrice<=Variation.PricePolicy: Variation=56042567|Price=$2,429.99"
		},
		{
			"Code": "Pricing",
			"Text": "CartItem.SellPrice<=PriceCard.ActiveSnapshot: Price=$6.00|Qty=5.0"
		},
		{
			"Code": "Pricing",
			"Text": "CartItem.ListPrice<=SellableItem.Variation.ListPrice: Price=$2,429.99"
		}
	],
	"ChildComponents": []
}

OrderCloud stores the resolved UnitPrice on the line item from the respective PriceBreak, prioritising the SalePrice over Price.

For orders in an unsubmitted state, the /products/ resource may be used to retrieve the product information will return the the current active snapshot, however once the order has been placed the product and price schedules resources are no longer considered the source of truth. If price schedule information, e.g. price breaks, sale start/end dates, etc. is required for historical and reconciliation purposes, a webhook can be created on the order submit endpoint to persist the information on the line items’ xp.

The other aspect of note is that the Currency is set at the order level, which applies to all monetary values on the order and line items.

"Order": {
  "ID": "MyOrder"
  ...
  "Currency": "USD"
  ...
},
"LineItems": [
  {
    "ID": "MyLineItem",
    ...
    "UnitPrice": 2429.99,
    ...
  }
]

Cart Line vs Line Item Totals

In the table below, we see a comparison between the cart line totals side by side with the equivalent line item totals. The notable differences are as follows:

XC Adjustments may include taxes, fulfillment fees, and promotion discounts, whereas OrderCloud only includes PromotionDiscount. Extended properties (xp) can be leveraged to persist taxes and fulfillments.
XC inverts the promotion discount adjustments so a $20 discount will be represented as -$20 in XC, so calculation of the GrandTotal is valid.
XC’s GrandTotal effectively matches the OrderCloud’s LineTotal as taxes and fulfillment fees aren’t flagged with IncludeInGrandTotal.

CartLine (XC)	Calculation	LineItem (OC)	Calculation	Match
`SubTotal`	`SellPrice` * `Quantity`	`LineSubtotal`	`UnitPrice` * `Quantity`	Yes
`AdjustmentsTotal`	Sum of all line-level `Adjustments`.	`PromotionDiscount`	Sum of all line item-level promotion discount amounts applied for the current line item.	No
`GrandTotal`	`SubTotal` + sum of line-level adjustments, where adjustments are flagged with `IncludeInGrandTotal` being `true`.	`LineTotal`	`LineSubtotal` – `PromotionDiscount`	Yes
`PaymentsTotal`	Payments not considered at line-level without customisation.			N/A

Extending the Cart and Cart Lines vs Order and Line Items

Those familiar with the SXA storefront and the Commerce Engine will be pleased with the significantly reduced development efforts involved in extending the order and order line items. Gone are the days of the plumbing extended strongly-typed model classes through several application layers in strongly-typed classes and dependency injection. And that’s just the storefront. The Commerce Engine would typically require creating new endpoints and replacing several more classes.

OrderCloud’s extended properties (xp) is not only a dynamically built object in OrderCloud, but the OrderCloud .NET and JavaScript SDKs also represent xp as a dynamic type, meaning you can write to a new property within the xp in one class and read from it in another class without any plumbing.

var order = new Order();
order.xp.MyNewProperty = "My New Property Value";

var lineitem = new LineItem();
line.xp.MyLineItemProperty = true;

Merge Carts vs Transfer Order

A typical ecommerce feature is retaining a cart/unsubmitted order of a guest/anonymous user as they log in or register to the storefront. In the SXA storefront, the register component will essentially transfer ownership to the newly registered user, while the login component will merge the anonymous cart with registered user’s cart, if it exists, by copying across all cart lines. If Cart Line Rollup is enabled, quantities will be updated where appropriate instead of copying over the cart line.

Figure 8: XC merges the anonymous cart with the existing customer cart on log in (rollup enabled).

OrderCloud contains similar functionality in allowing ownership an order from an anonymous user to be transferred to a profiled (registered) user. For registration, the order will need to be explicitly transferred.

Where a profiled user logs in, the difference between transferring an order and XC’s merging of carts, is that the buyer user may now have two active unsubmitted orders. The implementor would need to manage merging the orders together and either explictly deleting the second order or let OrderCloud’s unsubmitted order cleanup process delete it.

Figure 9: OrderCloud transfers an anonymous order to an authenticated registered user.

Abandoned Cart/Order Cleanup

The Commerce Engine’s minions role is responsible for cleaning up abandoned and empty carts. As seen below the PurgeCartsMinion runs daily, removing empty carts that are more than 2 days old and carts that have not been updated for more than 14 days. Both the minion and purge carts policies are configurable.

{
  "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
  "WakeupInterval": "01.00:00:00",
  "ListsToWatch": [
    "Carts"
  ],
  "FullyQualifiedName": "Sitecore.Commerce.Plugin.Carts.PurgeCartsMinion, Sitecore.Commerce.Plugin.Carts",
  "ItemsPerBatch": 10,
  "SleepBetweenBatches": 500
}

{
  "$type": "Sitecore.Commerce.Plugin.Carts.PurgeCartsPolicy, Sitecore.Commerce.Plugin.Carts",
  "AbandonedCartsThreshold": 14,
  "EmptyCartsThreshold": 2
}

In OrderCloud, unsubmitted order cleanup is an internal automated process with the rules outlined below, which are not configurable.

User Type	Has Line Items?	Retention Policy
All	No	24 hours
Anonymous	Yes	7 days
Profiled	Yes	90 days from LastUpdated date

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.

Orders

POST /orders/{direction}

In the Architecture Overview, we note that the cart equivalent in OrderCloud is an unsubmitted order. While no direct data mapping required, the following table details the alignment with XC.

OC Property	Data Type	Required	Notes
direction	string	Yes	Is a resource parameter, not body property. Set to `Outgoing` for buyer users.
ID	string	No	Allowing the ID to be generated by the platform effectively matches XC order behaviour.
FromCompanyID	string	No	This value will default to the buyer, which effectively matches XC.
ToCompanyID	string	No	This value will default to the marketplace owner, which effectively matches XC.
FromUserID	string	No	Defaults to the current user context.
BillingAddressID	string	No	Not required at the time of creation.
ShippingAddressID	string	No	Not required at the time of creation.
Comments	string	No
ShippingCost	number	No	Not required at the time of creation.
TaxCost	number	No	Not required at the time of creation.
xp	object	No	Any custom components required for the initial state can be added to xp.

Line Items

POST /orders/{direction}/{orderID}/lineitems

Adding a Cart Line vs Line Item has covered how to align the create line ltem request to align with XC. The following table covers the full view of the request.

OC Property	Data Type	Required	XC Property	Notes
direction	string	Yes		Is a resource parameter, not body property. Set to `Outgoing` for buyer users.
orderID	string	Yes		Is a resource parameter, not body property. OrderCloud’s order.ID
ID	string	No		Both XC and OrderCloud generate this ID by default.
ProductID	string	Yes	ItemId	Only the SellableItemId portion of the ItemId is required.
Quantity	string	Yes	Quantity	This value will default to the marketplace owner, which is effectively matches XC.
UnitPrice	string	No		Will be resolved from the PriceSchedule assignment of the current user context.
CostCenter	string	No
DateNeeded	string	No
ShippingAccount	string	No
ShippingAddressID	string	No
ShipFromAddressID	string	No
InventoryRecordID	string	No
Specs	object	No	ItemId	Used over variant ID. All spec IDs and specOptionIDs that represent the variant product will need to be specified.
xp	object	No		Custom components can be added to xp as needed.

References

Continue the Series

March 14, 2022January 10, 2023

Transitioning from Sitecore Experience Commerce to OrderCloud: Sellable Items To Products

Reading Time: 8 minutes

In this article, we will review and compare Sitecore Experience Commerce sellable items and OrderCloud products to facilitate developers looking to transition from XC to OrderCloud as well as identify a path for migration of existing XC solutions to OrderCloud.

Conceptual Architecture and Features

Physical vs Digital Sellable Items

In XC, a sellable item is considered digital if it contains a tag that is also registered to the DigitalItemTagsPolicy. Digital products will not track inventory and will modify the delivery step of the checkout flow to collect information relevant to digital items, such as an email address and custom messaging, rather than a delivery address and shipping provider information, which is relevant for physical items.

As OrderCloud is impartial to the nature of the products, using existing platform functionality and extended properties xp, a solution can opt into tracking product types and apply custom behaviour the achieve bespoke business requirements. For example, to model products as digital as per XC, we can disable inventory tracking at the product level and copy the tags to the product’s extended properties. The middleware and storefront applications can then identify products with this information as representing digital items and provide custom behaviour throughout the storefront to match that of the SXA storefront.

{
  "Name": "MyDigitalProduct",
  "Inventory": {
    "Enabled": false
  },
  "xp": {
    "tags": "subscription"
  }
}

Sellable Items vs Products

In XC, sellable items can be represented as standalone products, which are sellable items without variations, or as a product family, which consists of a number of item variations each representing an individual product that share mostly similar properties to the other item variations.

OrderCloud can also represent products as both standalone product or a product with variants.

Figure 1: Sellable items with and without item variations vs products with and without variants

Item Variations vs Variants

In XC, the item variations are created within a sellable item entity, each representing its own unique product.

Variation properties are defined in the environment role configuration under VariationPropertyPolicy and sellable item families are expected to use a subset of these properties to create unique combinations.

In OrderCloud, the architecture of product families have the same intention, however there is enforcement around creating only unique variations using specs and spec options. A spec closely relates to the VariationPropertyPolicy in that it specifies the property that will break down the product into a variant, while the spec option specifies all of the values that will be assigned to the spec. A product can have multiple specs assigned, e.g. the first spec could represent colors while the second could represent sizes.

While specs can then be assigned to more than one product, there’s more control in creating specs that are unique to products even if they do represent the same property type, such as size, as this will reduce the long term maintenance.

Figure 2: The product-spec assignment overview.

OrderCloud then provides the endpoint, POST /products/{productID}/variants/generate, to generate variants from all possible combinations of the assigned specs. Referencing figure 3 it can be noted that when migrating sellable items from XC there will be instances where not all combinations are required, however any unwanted variants can be disabled.

Figure 3: An example of a sellable item with item variations vs a product with generated variants.

Item Variation Corruption

While the SXA storefront and commerce data provider will utilise the VariationPropertyPolicy configuration for the item variation controls on the product details page in the storefront, there is no validation during item variation creation. This means that is is possible to corrupt sellable item families in the following ways:

Two or more varations share the same values across all of their variation properties. In figure 4, the product family utilises variation properties color and size, however item variations C and D are both configured with same color and size. In this instance, duplication may have been unintentional or a third variation property is missing that could make the variation unique. The Style property could be added in this instance to all item variations assuming the values between item variations C and D would be different.
The subset of variation properties are not all populated with values. In figure 4, the Color and Size properties are filled out for all item variations, except for item variation E which has a null value for Size.

Figure 4: Examples of how item variations can be inadvertently corrupted.

In figure 4, the Style property is null for all item variations.

Folding Sellable Items with Variations into Standalone Products

During sellable item migration there are two more scenarios that may come up, specifically in relation to sellable items with a single item variation. The first is in noting point 2 of the item variation corruption, a sellable item is flagged as corrupted as no variation properties of the item variation have values, which can be easily folded into a standalone sellable item.

The second scenario is where the single item variation does contain values for one or more variation properties. Here, is where further consideration may be required as to whether this item variation should be folded back into a standalone sellable item. The reason for this consideration is because the Commerce Engine sets a global set of variation properties, however this may not necessary apply to the sellable item in question, but was designed this way because the global configuration in the VariationPropertyPolicy.

Figure 5: Opportunities to fold sellable items with variations into standalone sellable items.

Static and Dynamic Bundles

XC has special product types called static bundles and dynamic bundles, which are configurations of sellable items that are sold together. These bundles can either represent a fixed group of sellable items or a list of sellable items with alternate sellable items, which can be substituted out by the user, and/or be an optional extra into the bundle.

OrderCloud currently does not currently support product bundling natively, however by leveraging the product’s xp it is possible to model product bundles and have functionality be controlled by middleware and buyer and seller applications.

Workshopping product bundle models and behaviour is outside of the scope of this analysis.

Extended Properties

In XC, a sellable item can have its properties extended via composer templates or programatically with custom components, while item variations only be extended programatically. These can be generally be translated over to OrderCloud using its eXtended Properties (xp), however considerations will be required around non-standard data types.

Images

XC leverages Sitecore’s media library for hosting images and stores the Sitecore Id of the image on the ImagesComponent of the sellable item or variant it’s associated to.

Over in OrderCloud, products don’t have an explicit property for images as it relies on external systems, such as DAMs or CDNs, to host imagery instead. In addition, the OrderCloud philosphy is that as there is no one-size-fits-all solution when it comes to working with product images, so the absence of a dedicated property provides the flexibility of allowing a bespoke data model to be added to the product’s xp to best represent the client’s business requirements. Examples of potential requirements include, a single array of images (image urls), image sets representing different views or components of a product, image sets representing varying quaility or sizing for omni-channel optimisation. etc.

Relationship Definitions

XC has a concept of relationship definitions, which allows sellable items to have a relation to another sellable item with a given context. For example, the Habitat catalog relationship definitions for associated sellable items for installation, training, warranty, and most notably related sellable items.

Figure 6: Related sellable items relationship

The Commerce Engine and BizFx application provides an interface for creating these relationships and applies validation to ensure that the related products exist and are not duplicated. The Commerce Engine also includes smarts to filter out invalid sellable items for a given context, e.g. inactive sellable items, sellable items that are not associated to the current catalog, etc.

In OrderCloud, custom product to product assignments are not native in the platform, however a list of associated products can be added to the product’s xp, e.g. xp.RelatedProducts, to represent the relationship. To retrieve the products, a filtered product search, under the me resource, can be queried using the product’s IDs, which will automatically exclude products that don’t exist, are inactive, or are not assigned to the user, e.g. /me/products?ID=<Product B>|<Product C>|<Product D>.

Figure 7: XC related products association architecture vs. a sample approach using xp in OrderCloud.

Inventory and Pricing

The topics of inventory and pricing comparisons between XC and OrderCloud can be found in their dedicated article in Transitioning from Sitecore Experience Commerce to OrderCloud: Inventory and Pricing.

Other Considerations

Entity Versioning and Workflow

As OrderCloud has no concept of entity versioning, one approach towards migration is to only migrate the latest published versions of sellable items. In a similar manner the publishing workflow that applies to sellable items may see a project consider the latest entity version as the source of truth regardless of its published state. Considerations would need to be made on project by project basis, which may entail a level of data cleansing prior to migration.

Property Localisation

XC allows entity properties to be localisable for content that can be displayed in multiple languages. OrderCloud does not explicitly support property localisation, however localisation can be achieved by creating locale-specific entities as documented in How to Globalize your eCommerce.

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.

Products

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
OwnerID	string	No	N/A	N/A	N/A
DefaultPriceScheduleID	string	No	SellableItem	ListPrice	Money	PriceSchedule will be created from the SellableItem’s ListPrice, using the Product.ID as the Price Schedule’s ID.
AutoForward	bool	No	N/A	N/A	N/A
ID	string	No	SellableItem	FriendlyId	string
Name	string	Yes	SellableItem	DisplayName	string
Description	string	No	N/A	N/A	N/A
QuantityMultiplier	int	No	N/A	N/A	N/A
ShipWeight	float	No	[ItemSpecificationsComponent]	Weight	double
ShipHeight	float	No	[ItemSpecificationsComponent]	Height	double
ShipWidth	float	No	[ItemSpecificationsComponent]	Width	double
ShipLength	float	No	[ItemSpecificationsComponent]	Length	double
Active	boolean	No	SellableItem	Published	boolean	This assumes only the latest published entity version is being migrated.
ShipFromAddressID	string	No	N/A	N/A	N/A
Inventory.Enabled	boolean	No	N/A	N/A	N/A	Virtual products won’t have inventory in either XC or OrderCloud. This should be set to disabled if any of the XC tags contain a value representing an XC virtual product.
Inventory.NotificationPoint	int	No	N/A	N/A	N/A
Inventory.VariantLevelTracking	boolean	No	N/A	N/A	N/A
Inventory.OrderCanExceed	boolean	No	N/A	N/A	N/A
Inventory.QuantityAvailable	int	No	InventoryInformation	Quantity	int	If transitioning a single inventory set/ record per product.
DefaultSupplierID	string	No	N/A	N/A	N/A
AllSuppliersCanSell	boolean	No	N/A	N/A	N/A
xp	object	No	N/A	N/A	N/A	XC composer views and programatic components can be added to xp as needed.
xp.Brand	string	No	SellableItem	Brand	string
xp.Manufacturer	string	No	SellableItem	Manufacturer	string
xp.TypeOfGood	string	No	SellableItem	TypeOfGood	string
xp.Tags	list	No	SellableItem	Tags	list	Convert to list of string using name property only.
xp.ItemDefinitions	list	No	[CatalogsComponent].[CatalogComponent]	ItemDefinition	string	The ItemDefinition of each CatalogComponent should be added to the list, excluding duplicate values.
xp.RelatedProducts	list	No	Relationship (Commerce List)	Id	string	The relationships are stored in lists, not entities. All Ids will need to be parsed to their friendly ids.

Specs

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
ID	string	No	SellableItem ItemVariationComponent	FriendlyId <variation property>	string	Recommended using ‘{SellableItem.FriendlyId}_<variation property name>’ to create unique name.
ListOrder	integer	No	N/A	N/A	N/A
Name	string	Yes	ItemVariationComponent	<variation property>	string	The name of the variation property, not the value of the variation property.
DefaultValue	string	No	N/A	N/A	N/A
Required	boolean	No	N/A	N/A	N/A	Set to `true`.
AllowOpenText	boolean	No	N/A	N/A	N/A	`false` by default.
DefaultOptionID	string	No	N/A	N/A	N/A
DefinesVariant	boolean	No	N/A	N/A	N/A	Set to `true`.
xp	object	No	N/A	N/A	N/A

Spec Options

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
specID	string	Yes	SellableItem ItemVariationComponent	FriendlyId <variation property>	string	See Spec Data Mapping ID property.
ID	string	No	ItemVariationComponent	<variation property>	string	The value of the variation property.
Value	string	Yes	ItemVariationComponent	<variation property>	string	The value of the variation property.
ListOrder	integer	No	N/A	N/A	N/A
IsOpenText	boolean	No	N/A	N/A	N/A	`false` by default.
PriceMarkupType	string	No	N/A	N/A	N/A
PriceMarkup	number	No	N/A	N/A	N/A
xp	object	No	N/A	N/A	N/A

Spec Product Assignments

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
SpecID	string	Yes	SellableItem ItemVariationComponent	FriendlyId <variation property>	string	See Spec Data Mapping ID property.
ProductID	string	Yes	SellableItem	FriendlyId	string
DefaultValue	string	No	N/A	N/A	N/A
DefaultOptionID	string	No	N/A	N/A	N/A

Variants

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
productID	string	Yes	SellableItem	N/A	N/A
variantID	string	Yes	ItemVariationComponent	Id	string
ID	string	No	ItemVariationComponent	Id	string
Name	string	Yes	ItemVariationComponent	DisplayName	string
Description	string	No	ItemVariationComponent	N/A	N/A
Active	boolean	No	ItemVariationComponent	Disabled	boolean	Value to be inverted. Set to `false` if not a valid variant.
ShipWeight	float	No	[ItemSpecificationsComponent]	Weight	double
ShipHeight	float	No	[ItemSpecificationsComponent]	Height	double
ShipWidth	float	No	[ItemSpecificationsComponent]	Width	double
ShipLength	float	No	[ItemSpecificationsComponent]	Length	double
Inventory.QuantityAvailable	int	No	InventoryInformation	Quantity	int	If transitioning a single inventory set/ record per product.
xp	object	No	N/A	N/A	N/A	XC composer views and programatic components can be added to xp as needed.
xp.Tags	list	No	SellableItem	Tags	list	Convert to list of string using name property only.

References

Continue the Series

March 11, 2022January 10, 2023

Transitioning from Sitecore Experience Commerce to OrderCloud: Customers and Buyers – API Access

Reading Time: 7 minutes

In this article, we will review and compare API Access for 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.

Conceptual Architecture and Features

Storefront API Access to the Commerce Systems

One aspect that developers tend to glaze over is how an SXA storefront interacts with the Commerce Engine. This is because the installation scripts apply the necessary configurations for the installed topology without the need for further manual intervention.

In an OrderCloud solution, the storefront will be configured to interact with the OrderCloud API server for the relevant region and environment, as documented in OrderCloud Supported Regions and Environments, that hosts the marketplace instance.

Resources

In the Commerce Engine, the CommerceODataController actions are registered to either the /api or /commerceops route, which creates the API under these two primary resources. The api route typically hosts actions that a storefront or the Commerce Business Tools (BizFx) would request, while the commerceops route hosts actions for dev ops interactions by dev ops users and the commerce data provider.

In OrderCloud, resources are not grouped up into resource buckets, however in the OrderCloud portal there is logical grouping within the UI to help navigate between related resources, as seen in figure 1.

For storefront users, the /me and /order resources will cover account management and creation of orders respectively.

Figure 1: Logical grouping of resources in the OrderCloud portal.

Authentication

The Sitecore Identity Server provides bearer token authentication for SXA storefront requests made to the Commerce Engine using the Commerce Engine Connect client, which is configured across Sitecore, Sitecore Identity Server, and Commerce Engine applications.

SXA customer registration and login functionality is accomplished using the SQL authorization provider, instead of the Sitecore Identify Server. This also segregates customer authentication data stored in the security database from commerce data stored in the commerce database.

The related commerce customer entity is created in the commerce database during account creation and the commerce customer reference is stored against the customer account in the security database.

Figure 3: Storefront users are created with a corresponding commerce customer entity to segregate membership data from commerce data.

In an OrderCloud storefront implementation, authentication is handled within OrderCloud itself using API clients, in a similar fashion to Sitecore Identity Server’s clients, returning limited lifetime bearer tokens.

Figure 4: OrderCloud authentication via API client overview.

Storefront user data is stored under a single object and users are typically authenticated directly with all subsequent requests containing the context of a storefront user.

Roles and Authorisation

Requests to the Commerce Engine will see the bearer token validated, which will determine the roles of the authenticated user and compare them to the roles of the API resource, which is configured in the Commerce Engine under the ControllerMethodRolesPolicy in Global.json.

{
  "$type": "Sitecore.Commerce.Core.ControllerMethodRolesPolicy, Sitecore.Commerce.Core",
  "ControllerMethodRegularExpression": "/commerceops/",
  "AuthorizedRoles": [
    "sitecore\\Commerce Business User",
    "commerce\\runtime"
  ]
},
{
  "$type": "Sitecore.Commerce.Core.ControllerMethodRolesPolicy, Sitecore.Commerce.Core",
  "ControllerMethodRegularExpression": "/api/",
  "AuthorizedRoles": [
    "sitecore\\Commerce Business User",
    "commerce\\runtime"
  ]
}

Requests not containing an authorized role will be rejected by the Commerce Engine with the exception of the Commerce Engine Connect client being a special case in that the Commerce Engine identifies this user and appends the commerce\runtime role to the request context to effectively brute force authorisation for its requests.

In contrast, OrderCloud has predefined roles for the various resources, which is detailed further in Understanding Security Profiles, providing more granular control over the resources a user has access to.

During the authentication process the roles are resolved from the user being authenticated, based on security profile assignments at the company, user group, and user levels.

To replicate the behaviour from XC, while having considerations for the necessary restrictions to API resources that wouldn’t be utilised by a storefront user, the following roles would be assigned to a security profile for storefront users.

{
  "Roles": [
    "Shopper",
    "MeAdmin",
    "MeXpAdmin",
    "MeAddressAdmin",
    "MeCreditCardAdmin",
    "PasswordReset"
  ]
}

Anonymous and Registered Users

In the SXA storefront, the customer id of anonymous/guest users and registered customers are passed in as a request header, which the Commerce Engine then resolves to the anonymous or registered user.

In OrderCloud, the user context needs to be resolved at the time of authentication, which will then be passed on to subsequent requests via the access token. Registered users are authenticated with username and password, while anonymous users are authenticated against an API client configured with an IsAnonBuyer flag and the default context user, which is used for resolving roles and not a user context when interacting with the OrderCloud API.

In figure 5, we see an API client configured with the IsAnonBuyer set as true and the DefaultContextUserName set to BUYER USER A. The roles configured to Security Profile A, which is assigned to Buyer A will be resolved when attempting to authenticate a registered buyer user or an anonymous user.

BUYER USER A is created for the specific purpose of being the anonymous user template as using a real user that can be modified or deleted at any time can have adverse effects on the anonymous user behaviour.

Figure 5: API client – buyer – security profile relationship and configuration example for registered and anonymous storefront users.

Service Proxy vs SDKs and Catalyst

The SXA storefront solution, including custom code, typically communicates with the Commerce Engine via the Service Proxy – an SDK containing Commerce Engine data models and strongly typed wrappers for the API. The Service Proxy simplifies custom development effort and complexity, which can also be regenerated after modifying the Commerce Engine to ensure the integrity of the library.

Figure 6: Commer Engine API access via the Service Proxy.

OrderCloud also provides a JavaScript and .Net SDK for the OrderCloud data models and strongly typed wrappers for all public endpoints. The JavaScript SDK allows requests to be made directly from the client browser rather than passed through middleware, whereas the .Net SDK is intended for the middleware for requests that typically require wrapped logic or even placeholder wrappers to insert logic at a later date.

The OrderCloud catalyst is another .Net library which provides additional helpers for authentication, performant bulk requests, error handling, jobs, project setup, etc.

Figure 7: OrderCloud API access via SDK and Catalyst libraries.

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.

Security Profile

The security profile mapped below represents storefront users only. The BizFx Business Tools users would have a different configuration, most notably for roles.

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
ID	string	No	Site (Sitecore)	Domain	string
Name	string	Yes	Site (Sitecore)	Domain	string
Roles	array	No	Shopper, MeAdmin, MeXpAdmin, MeAddressAdmin, MeCreditCardAdmin, PasswordReset	N/A	N/A
CustomRoles	array	No	N/A	N/A	N/A
PasswordConfig.LimitPasswordReuse	integer	No	N/A	N/A	N/A
PasswordConfig.MaxConsecutiveDupeChars	integer	No	N/A	N/A	N/A
PasswordConfig.MaximumPasswordAge	integer	No	N/A	N/A	N/A
PasswordConfig.MinimumPasswordAge	integer	No	N/A	N/A	N/A
PasswordConfig.AllowedFailedAttempts	integer	No	(web.config) configuration/system.web/ membership/add[name=”sql”]	maxInvalidPasswordAttempts	string	Set to 5
PasswordConfig.LockoutDuration	integer	No	N/A	N/A	N/A
PasswordConfig.UpperCaseRequired	boolean	No	N/A	N/A	N/A
PasswordConfig.LowerCaseRequired	boolean	No	N/A	N/A	N/A
PasswordConfig.SpecialCharacterRequired	boolean	No	N/A	N/A	N/A
PasswordConfig.NumericRequired	boolean	No	N/A	N/A	N/A
PasswordConfig.MinimumCharacterCount	integer	No	(Commerce.XA) Registration.cshtml RegistrationUserInputModel.cs	data_val_length_min MinimumLength	string integer	Sitecore’s default value is 6, while OrderCloud has a minimum value of 10.

Security Profile Assignment

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type
SecurityProfileID	string	Yes	Site (Sitecore)	Domain	string
BuyerID	string	No	Site (Sitecore)	Domain	string
SupplierID	string	No	N/A	N/A	N/A
UserID	string	No	N/A	N/A	N/A
UserGroupID	string	No	N/A	N/A	N/A

Buyer User (Anonymous User)

The anonymous buyer user is created to represent an instance of an anonymous user. This user is fleshed out with hard-coded values for mandatory properties.

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
buyerID	string	Yes	Site (Sitecore)	Domain	string	Is a resource parameter, not body property.
ID	string	No	N/A	N/A	string	“anonymous-user”
Username	string	Yes	N/A	N/A	string	“{buyerId}-anonymous-user”
Password	string	No	N/A	N/A	N/A
FirstName	string	Yes	N/A	N/A	N/A	“Anonymous”
LastName	string	Yes	N/A	N/A	N/A	“User”
Email	string	Yes	N/A	N/A	N/A	“anonymous@user.com”
Phone	string	No	N/A	N/A	N/A
TermsAccepted	string	No	N/A	N/A	N/A
Active	boolean	Yes	N/A	N/A	N/A	Set to `true`
xp	object	No	N/A	N/A	N/A

API Client

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
ClientSecret	string	No	N/A	N/A	N/A
AccessTokenDuration	integer	Yes	N/A	N/A	N/A	Set to 600 (maximum)
Active	boolean	No	N/A	N/A	N/A	Set to `true`
AppName	string	Yes	Site (Sitecore)	Domain	string
RefreshTokenDuration	integer	No	N/A	N/A	N/A
DefaultContextUserName	string	No	Anonymous Buyer User (OrderCloud)	Username	string
AllowAnyBuyer	boolean	No	N/A	N/A	N/A
AllowAnySupplier	boolean	No	N/A	N/A	N/A
AllowSeller	boolean	No	N/A	N/A	N/A
IsAnonBuyer	boolean	No	N/A	N/A	N/A	Set to `true`
OrderCheckoutIntegrationEventID	string	No	N/A	N/A	N/A
MinimumRequiredRoles	array	No	N/A	N/A	N/A
MinimumRequiredCustomRoles	array	No	N/A	N/A	N/A
MaximumGrantedRoles	array	No	N/A	N/A	N/A
MaximumGrantedCustomRoles	array	No	N/A	N/A	N/A
xp	object	No	N/A	N/A	N/A

API Client Assignment

Technically, the API client assignment can be skipped and the AllowAnyBuyer property on the API client can be set to true instead, however this example creates an API client per storefront, which may be preferrable to allow the API client configuration to be modified later without affecting the other storefronts.

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type
ApiClientID	string	Yes	Api Client (OrderCloud)	ID	string
BuyerID	string	No	Site (Sitecore)	Domain	string
SupplierID	string	No	N/A	N/A	N/A

References

Continue the Series

January 30, 2022January 10, 2023

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

Reading Time: 5 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.

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.

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

To bring across customer addresses into OrderCloud, figure 8 shows that we can create buyer user addresses, via the /me/addresses resource, creating a custom IsPrimary flag in the buyer address xp.

Figure 8: Buyer user address architecture in OrderCloud.

Buyer user addresses, also contain Shipping and Billing properties, which can facilitate filtering addresses for the purpose of being retrieving and setting for an order’s shipping address or billing address respectively. As the SXA Storefront allows customer addresses to be used for both of these addresses, these flags should also 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.
Email	string	Yes	Customer	Email	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 User Addresses

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
Shipping	boolean	No	N/A	N/A	N/A	Set to `true`
Billing	boolean	No	N/A	N/A	N/A	Set to `true`
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