Cart domain model

Version: 10.3

This section describes the domain model that represents the cart and its constituent Data Transfer Objects (DTO). The domain model is used when a Sitecore developer needs to interact with the cart and transfer cart data back and forth to the ECS. All business logic for carts is implemented in the service layer API, which must be used to manipulate carts.

Some examples of cart domain model usage:

To collect information from visitors.
To display information in renderings.
To use information for personalization.
To pass cart information to the external commerce system.
To return cart total from pricing service layer.

Note

Because the cart has strong references to Price and Total, they are included in the domain model, but methods for calculating the total and getting prices are part of the Pricing integration service layer.

The following class diagram shows the domain model. All the Cart classes, prefixed with Cart, on the left, are described in this section, whereas the Price, Total and TaxTotal classes on the right are described in the Pricing section and are manipulated by the pricing API. The Party, ShippingInfo and PaymentInfo classes are part of the Customer, Shipping and Payment service layers respectively.

Cart classes that are part of the Cart domain model.

Note

The domain model consists of classes that make up the contracts with the external system. The contracts are defined as classes instead of interfaces to allow the model to be easily extended later if needed. This follows the best practice guidelines defined in the Framework Design Guidelines book.

Default implementation of the contracts are delivered as part of Connect. If an actual Connect provider with an external commerce system contains more functionality than provided by default, the implementation can be replaced. All instantiation of actual classes will be handled using the Factory design pattern.

Cart keys

A cart has two unique composite keys:

CartId (aka. ExternalCartId), ShopName

Some methods, such as LoadCart, use this key to locate a cart.
UserId, CustomerId, CartName, ShopName

Some methods, such as GetCarts and CreateCart, use this key.

Class: Cart Base

The Cart Base represents a summary of the main cart data and is used as return values from GetCarts and CreateOrResumeCart in case of multiple matching carts.

The Cart class inherits from the Cart Base class. For more information, see Class: Cart.

Name	Type	Description
Name	String	Can be used to name a cart. The property is optional to use, but can be used in solutions where a single visitor/user can have multiple carts. In order to differentiate between the carts, a string value must be provided.
UserId	String	The identifier for the user of the cart, can be: The contact ID or Identifier provided by Sitecore. A user id provided by Sitecore. A user ID provided by ECS.
CustomerId	String	The identifier for the customer of the cart. The customer cannot manipulate the cart directly, but only indirectly through the user.
ShopName	String	The shop name where the cart belongs, used to enable multishop support. In implementation it can correspond to the website name if there is a one-to-one mapping between the website and the shop. All API methods take `ShopName` as a parameter.
IsLocked	Boolean	Indicates if the cart is locked or not. A cart is typically locked during part of the checkout process, especially after initiation of payment.
CartType	String	Contains type values for different usage of the cart. For example: Regular, Gift card, Wish list, Recurring-cart. In the default implementation, only the Regular value is used and tested. It can be extended later and customized in the actual Connect provider implementation.
CartStatus	String	A status code: InProcess or Abandoned. It can be extended later and customized in the actual Connect provider implementation.
CurrencyCode	String	Represents the currency code of items in the cart.

Class: Cart

The Cart class is responsible for representing the collection of products a customer is planning to buy. It is used when the content of the cart needs to be displayed or when Sitecore needs to determine the content of the cart for any other purpose (such as personalization).

The Cart class inherits its base cart data from the Cart Base class. For more information, see Class: Cart Base.

Name	Type	Description
`CartLines`	`List<CartLine>`	Contains the cart lines.
`Adjustments`	`List<Adjustment>`	Collection of adjustments that describe any discrepancies between the total and the sum of the prices of the individual cart line items. Examples are coupon codes (manually triggered), and shipping surcharges (automatically triggered)
`CartTotal`	`Total`	Represents the total value for the products in the cart.

Name

Type

Description

CartLines

List<CartLine>

Contains the cart lines.

Adjustments

List<Adjustment>

Collection of adjustments that describe any discrepancies between the total and the sum of the prices of the individual cart line items.

Examples are coupon codes (manually triggered), and shipping surcharges (automatically triggered)

CartTotal

Total

Represents the total value for the products in the cart.

Class: Cart Line

The Cart Line class represents a line in the shopping cart. It represents something that a visitor has added to their cart, along with the quantity of the item that was added to the cart. It also represents the position of the line relative to other lines in the cart (for controlling the order the lines appear when the lines are displayed).

Name	Type	Description
`ExternalCartLineId`	`String`	Unique identifier for the cart line in the commerce system. Will be empty when adding cart lines and can be set by the ECS. Can be specified when removing and updating cart lines.
`Quantity`	`Decimal`	The quantity of the specific cart product in the cart.
`Product`	`CartProduct`	The cart line product. The Cart Product object contains the reference to the actual product
`LineNumber`	`Int`	The position of the cart line in the cart. Can be specified when removing and updating cart lines. Can be empty when adding cart lines.
`Adjustments`	`List<Adjustment>`	Collection of adjustments that describe any discrepancies between the total and the cart item price. The actual content of the adjustments are provided by the ECS.
`Total`	`Total`	Represents the total for the product represented by the cart product (subitem).This value is the same as the total on the cart product (subitem) multiplied by the quantity including the list of Adjustments. Read-only. Is reserved for the Pricing Service Layer and must not be supplied when adding, removing, or updating cart lines.
`SubLines`	`List<CartLine>`	Recursive sublines. For example, if the cart item is a bundled product, the sublines are the individual products that make up the bundle. Another example is services such as insurance that are added to a product

Class: Cart Product

The Cart Product class represents a product that can be referenced by a Cart Line class object. It can also be a subitem of a Cart Product class object in the case of bundling or insurance, and so on.

Name	Type	Description
`ProductId`	`String`	Unique identifier for the product in the external commerce system.
`SitecoreProductItemId`	`ID`	Shortcut for referencing the product item in Sitecore directly.
`Options`	`List<Option>`	Represents visitor-specified product options (such as engraving=Adam).
`LineNumber`	`Integer`	Gets the position of the cart item in the cart.
`Adjustments`	`List<Adjustment>`	Collection of adjustments that describe any discrepancies between the total and the price of the cart item's product.
`Price`	`Price`	Contains the product price. Can be supplied when adding or updating cart lines to cart, but can also be set by the Pricing service layer during a call to GetCartTotal.

Class: Cart Adjustment

A cart adjustment describes a charge or a discount given on an instance of a Cart, Cart Line or Cart Line Product class.

Examples are:

Coupon codes (manually triggered) on instances of the Cart or the Cart Line classes.
Shipping surcharges on instances of the Cart or Cart Line classes (automatically triggered).

The adjustment can be a fixed amount or a percentage, but not both at the same time. If both an amount and percentage is applied, then two adjustments must be given and the LineNumber property specifies the order in which they are applied.

	Customer action	Data flow
Amount	Decimal	Amount that needs to be added to or subtracted from the subtotal. Only Amount or Percentage (see below) can be used at any one time
Description	String	A description of the charge or discount applied. The description could include a reference to a coupon code.
IsCharge	Boolean	If True, indicates that it is a charge, otherwise it is a discount.
Percentage	Float	A percentage that must be added or subtracted. Only Amount or Percentage can be used at any one time
LineNumber	Integer	If multiple adjustments are given, the LineNumber specifies the order in which the charge or discount is applied. The information stored in adjustments is used for presentation, showing calculation order and not for actual calculation to the cart.

Class: Cart Option

The Cart Option class represents a configurable or variable value that is specific to an item in the cart. An example of an option is engraving on a personalized product. When the engraving service is added to the cart, the text to engrave is also required. The Cart Option class represents this.

If an option has an additional charge, the option must be represented by a separate instance of the Cart Line Productclass. The option is only used to describe variables or settings on a specific instance of the Cart Line Productclass, not to handle adjustments or pricing changes.

Name	Type	Description
`OptionId`	`String`	An internal ID for the option, typically provided by Sitecore when the user adds an option to the cart line.
`Description`	`String`	An optional description referring to the type of option. For example, Engraving, Name on t-shirt and so on.
`Value`	`String`	The actual custom value

Do you have some feedback for us?

If you have suggestions for improving this article,