Commerce Cart API Reference
Corecommerce
Overview
Section titled “Overview”Cart operations use IOrderRepository and IOrderGroupFactory to create and manage shopping carts. Carts are named order groups stored per customer. The default cart name is "Default". Wishlist uses the name "Wishlist".
Namespace
Section titled “Namespace”Optimizely.Commerce.Order
Key interfaces
Section titled “Key interfaces”| Interface | Purpose |
|---|---|
IOrderRepository | Load, save, delete carts and orders |
IOrderGroupFactory | Create new cart and line item instances |
IOrderGroupCalculator | Calculate cart totals |
ILineItemValidator | Validate line items against inventory |
IOrderRepository — Cart methods
Section titled “IOrderRepository — Cart methods”Load<T>(Guid, string)
Section titled “Load<T>(Guid, string)”Loads a cart by customer ID and cart name.
Parameters
| Name | Type | Description |
|---|---|---|
customerId | Guid | Customer contact GUID |
name | string | Cart name (e.g., "Default", "Wishlist") |
Returns: T where T is ICart, or null if no cart exists
Save(IOrderGroup)
Section titled “Save(IOrderGroup)”Persists the cart to the database.
Parameters
| Name | Type | Description |
|---|---|---|
orderGroup | IOrderGroup | The cart to save |
Returns: OrderReference
Delete(OrderReference)
Section titled “Delete(OrderReference)”Removes a cart from the database.
Parameters
| Name | Type | Description |
|---|---|---|
orderRef | OrderReference | Reference returned from Save() |
Returns: void
Creating a cart
Section titled “Creating a cart”Create a new cart and add a line item
public class CartService
{
private readonly IOrderRepository _orderRepository;
private readonly IOrderGroupFactory _orderGroupFactory;
private readonly ICurrentMarket _currentMarket;
public CartService(
IOrderRepository orderRepository,
IOrderGroupFactory orderGroupFactory,
ICurrentMarket currentMarket)
{
_orderRepository = orderRepository;
_orderGroupFactory = orderGroupFactory;
_currentMarket = currentMarket;
}
public ICart GetOrCreateCart(Guid customerId)
{
var cart = _orderRepository.Load<ICart>(customerId, "Default")
.FirstOrDefault();
if (cart == null)
{
cart = _orderGroupFactory.CreateCart(
customerId,
"Default",
_currentMarket.GetCurrentMarket().MarketId);
}
return cart;
}
}Adding line items
Section titled “Adding line items”CreateLineItem(string, IOrderGroup)
Section titled “CreateLineItem(string, IOrderGroup)”Creates a new line item for a catalog entry code.
Parameters
| Name | Type | Description |
|---|---|---|
code | string | Catalog entry code (SKU) |
orderGroup | IOrderGroup | The parent cart |
Returns: ILineItem
Add item to cart
public void AddToCart(ICart cart, string skuCode, decimal quantity)
{
var lineItem = cart.GetAllLineItems()
.FirstOrDefault(li => li.Code == skuCode);
if (lineItem != null)
{
lineItem.Quantity += quantity;
}
else
{
lineItem = _orderGroupFactory.CreateLineItem(skuCode, cart);
lineItem.Quantity = quantity;
cart.GetFirstShipment().LineItems.Add(lineItem);
}
_orderRepository.Save(cart);
}Updating quantities
Section titled “Updating quantities”Update line item quantity
public void UpdateQuantity(ICart cart, string skuCode, decimal newQuantity)
{
var lineItem = cart.GetAllLineItems()
.FirstOrDefault(li => li.Code == skuCode);
if (lineItem == null)
throw new InvalidOperationException($"Item {skuCode} not in cart.");
if (newQuantity <= 0)
{
cart.GetFirstShipment().LineItems.Remove(lineItem);
}
else
{
lineItem.Quantity = newQuantity;
}
_orderRepository.Save(cart);
}Removing items
Section titled “Removing items”Remove item from cart
public void RemoveFromCart(ICart cart, string skuCode)
{
var shipment = cart.GetFirstShipment();
var lineItem = shipment.LineItems
.FirstOrDefault(li => li.Code == skuCode);
if (lineItem != null)
{
shipment.LineItems.Remove(lineItem);
_orderRepository.Save(cart);
}
}ILineItem properties
Section titled “ILineItem properties”| Property | Type | Description |
|---|---|---|
Code | string | Catalog entry code |
DisplayName | string | Product display name |
Quantity | decimal | Item quantity |
PlacedPrice | decimal | Original unit price |
ListPrice | decimal | List price before discounts |
DiscountedPrice | decimal | Price after discounts |
Named carts
Section titled “Named carts”| Cart name | Purpose |
|---|---|
"Default" | Primary shopping cart |
"Wishlist" | Saved items for later |
| Custom string | Any named cart for specific workflows |
Common exceptions
Section titled “Common exceptions”| Exception | Cause |
|---|---|
InvalidOperationException | Cart not found or line item missing |
InventoryRequestException | Requested quantity not available |
ValidationException | Invalid entry code or negative quantity |