Shopping carts

The shopping cart (or basket) is where the shopping and ordering process starts. This article describes the main components of a shopping cart using the abstraction APIs.

The cart APIs are built around the IOrderRepository interface, which lets you load, update, save, and delete carts. The cart objects are represented by the ICart interface, which extends the IOrderGroup interface.

The main reason to prefer IOrderRepository over the concrete classes is that it is implementation-independent. Whether the underlying implementation is the legacy cart mode or the more recent serializable mode, IOrderRepository works the same way — the providers handle all the work internally.

Load and create a cart

Each cart is identified by its name, customer ID, and market. IOrderRepository has multiple overloads and extension methods to create or load a cart. If a parameter is missing from the method call, the default value is used. For example, if you use the overload without a MarketId parameter, the current market is used.

To load a cart, use the .Load() method:

var cart = orderRepository.Load<ICart>(customerId, "Default");

This loads the existing cart and returns null if no cart exists.

To create a cart, use the .Create() method:

var cart = orderRepository.Create<ICart>(customerId, "Default");

As a best practice, use the LoadOrCreateCart extension method, which creates a cart if none exists or loads an existing one:

var cart = orderRepository.LoadOrCreateCart<ICart>(_customerContext.CurrentContactId, name);

Add items to a cart

To add an item to a cart, first create an ILineItem. IOrderGroup has an extension method called CreateLineItem, which takes the SKU code and returns an ILineItem instance. As a best practice, check whether the cart already has a line item with the same SKU. If it does, increase the quantity. Otherwise, create a new line item and add it to the cart.

var lineItem = cart.GetAllLineItems().FirstOrDefault(x => x.Code == code && !x.IsGift);
if (lineItem == null) {
  lineItem = cart.CreateLineItem(code, _orderGroupFactory);
  lineItem.DisplayName = entryContent.DisplayName;
  lineItem.Quantity = quantity;
  cart.AddLineItem(lineItem, _orderGroupFactory);
} else {
  var shipment = cart.GetFirstShipment();
  cart.UpdateLineItemQuantity(shipment, lineItem, lineItem.Quantity + quantity);
}

Remove items from a cart

To remove an item from a cart, remove it from the shipment. Normally, a cart has only one shipment, so removing the line item from the first shipment is enough.

var lineItem = cart.GetAllLineItems().FirstOrDefault(x => x.Code == code && !x.IsGift);
if (lineItem != null) {
  var shipment = cart.GetFirstShipment();
  shipment.LineItems.Remove(lineItem);
}

Validate a cart

Before a customer can place an order, validate the cart to ensure that it has sufficient quantity, that the prices are accurate and up to date, and that any promotions are applied correctly.

// _orderValidationService is an instance of OrderValidationService.
public IDictionary<ILineItem, IList<ValidationIssue>> ValidateCart(ICart cart) {
  return _orderValidationService.ValidateOrder(cart);
}

Save a cart

To save a cart, call IOrderRepository.Save on an instance of ICart:

orderRepository.Save(cart);