Order manipulation

12 min

Manipulation of purchase orders and related items is based on classes and methods in the EPiServer.Commerce.Order namespace.

These are the key interfaces:

IOrderRepository

IOrderRepositoryExtensions

IOrderGroupExtensions

IOrderGroupFactory

📘 Note If you have more than 10 cart instances, the cart cache is not helpful because cache invalidation can impact site performance. Use the episerver:commerce.DisableOrderRepositoryCache setting to turn off the cart cache. Only use this setting if you understand the consequences. (Applies to version 13.13.)

Create orders

When you create orders using the default implementation of IOrderGroupFactory, the Forms collection always contains an IOrderForm, and that form's Shipments collection always contains an IShipment. If you implement a custom IOrderGroupFactory, follow the same convention.

The following example shows how to create a cart, purchase order, and payment plan.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();

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

// Create purchase order
var purchaseOrder = orderRepository.Create<IPurchaseOrder>(contactId, "Default");

// Create payment plan
var paymentPlan = orderRepository.Create<IPaymentPlan>(contactId, "Default");

Load orders

The following example shows how to load a cart, wishlist, payment plan, and purchase order.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();

// Loading the cart returns null if it does not exist.
var cart = orderRepository.LoadCart<ICart>(contactId, "Default");
var cart = orderRepository.Load<ICart>(orderGroupId);
var cart = orderRepository.Load(orderReference) as ICart;

// Load all carts for the customer.
var carts = orderRepository.Load<ICart>(contactId, "Default");

// LoadOrCreateCart creates a cart if one does not exist.
var cart = orderRepository.LoadOrCreateCart<ICart>(contactId, "Default");

// Loading the wishlist returns null if it does not exist.
var wishlist = orderRepository.LoadCart<ICart>(contactId, "Wishlist");
var wishlist = orderRepository.Load<ICart>(orderGroupId);
var wishlist = orderRepository.Load(orderReference) as ICart;

// Load all wishlists for the customer.
var wishlists = orderRepository.Load<ICart>(contactId, "Wishlist");

// LoadOrCreateCart creates a wishlist if one does not exist.
var wishlist = orderRepository.LoadOrCreateCart<ICart>(contactId, "Wishlist");

// Loading a purchase order.
var purchaseOrder = orderRepository.Load(orderReference) as IPurchaseOrder;
var purchaseOrder = orderRepository.Load<IPurchaseOrder>(orderGroupId);

// Loading purchase orders for the customer.
var purchaseOrders = orderRepository.Load<IPurchaseOrder>(contactId, "Default");

// Loading a payment plan.
var paymentPlan = orderRepository.Load(orderReference) as IPaymentPlan;
var paymentPlan = orderRepository.Load<IPaymentPlan>(orderGroupId);

// Loading payment plans for the customer.
var paymentPlans = orderRepository.Load<IPaymentPlan>(contactId, "Default");

// Loading all orders for the customer.
var orders = orderRepository.Load(contactId, "Default");

Save orders

Note that the purchase order number should be unique. The following example shows how to save a cart, purchase order, and payment plan.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    
var reference = orderRepository.Save(cart);
var reference = orderRepository.Save(purchaseOrder);
var reference = orderRepository.Save(paymentPlan);
var reference = orderRepository.SaveAsPurchaseOrder(cart);
var reference = orderRepository.SaveAsPaymentPlan(cart);

Delete an order

The following example shows how to delete an order.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
    orderRepository.Delete(orderReference);

Create and delete an order form

The following example shows how to create and delete an order form.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
var cart = orderRepository.LoadCart<ICart>(contactId, "Default");

// Create and add a new order form (b2b).
var orderForm = orderGroupFactory.CreateOrderForm(cart);
cart.Forms.Add(orderForm);
orderForm.Name = "Default";

// Delete the order form.
cart.Forms.Remove(orderForm);

Add and remove shipments

The following example shows how to add and remove shipments from order forms.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();

var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
var cart = orderRepository.LoadCart<ICart>(contactId, "Default");

// Create and add a shipment to the first form.
var shipment = orderGroupFactory.CreateShipment(cart);
// Pass in orderGroupFactory for unit testing because a form will be created if none exists.
cart.AddShipment(shipment, orderGroupFactory);
// Set the address after adding to the collection because of an implementation limitation.
shipment.ShippingAddress = orderGroupFactory.CreateOrderAddress(cart);

// Create and add a shipment to the second form (b2b).
var secondForm = cart.Forms.Last();
var shipment = orderGroupFactory.CreateShipment(cart);
cart.AddShipment(secondForm, shipment);
// Set the address after adding to the collection because of an implementation limitation.
shipment.ShippingAddress = orderGroupFactory.CreateOrderAddress(cart);

// Remove the shipment from the first form.
cart.GetFirstForm().Shipments.Remove(shipment);

// Remove the shipment from the second form (b2b).
cart.Forms.Last().Shipments.Remove(shipment);

Add and remove payments

The following example shows how to add and remove payments from order form.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
var cart = orderRepository.LoadCart<ICart>(contactId, "Default");

// Create and add a payment to the first form.
var creditCard = orderGroupFactory.CreateCardPayment(cart);
var invoice = orderGroupFactory.CreatePayment(cart);
// Pass in orderGroupFactory for unit testing because a form will be created if none exists on the cart.
cart.AddPayment(creditCard, orderGroupFactory);
cart.AddPayment(invoice, orderGroupFactory);
// Set the address after adding to the collection because of an implementation limitation.
creditCard.BillingAddress = orderGroupFactory.CreateOrderAddress(cart);

// Create and add a payment to the second form (b2b).
var secondForm = cart.Forms.Last();
var creditCard = orderGroupFactory.CreateCardPayment(cart);
var invoice = orderGroupFactory.CreatePayment(cart);
cart.AddPayment(secondForm, creditCard);
cart.AddPayment(secondForm, invoice);
// Set the address after adding to the collection because of an implementation limitation.
creditCard.BillingAddress = orderGroupFactory.CreateOrderAddress(cart);

// Remove the payment from the first form.
cart.GetFirstForm().Payments.Remove(payment);

// Remove the payment from the second form (b2b).
cart.Forms.Last().Payments.Remove(payment);

Add line items to shipments

The following example shows how to add line items to shipments.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
var cart = orderRepository.LoadCart<ICart>(contactId, "Default");

// Add a line item to the first shipment on the first form.
var lineItem = orderGroupFactory.CreateLineItem("code", cart);

// Use orderGroupFactory for unit testing.
cart.AddLineItem(lineItem, orderGroupFactory);

// Add a line item to the second shipment on the first form.
var shipment = cart.GetFirstForm().Shipments.Last();
var lineItem = orderGroupFactory.CreateLineItem("code", cart);
cart.AddLineItem(shipment, lineItem);

// Add a line item to the first shipment on the second form.
var orderForm = cart.Forms.Last();
var lineItem = orderGroupFactory.CreateLineItem("code", cart);

// Add orderGroupFactory for unit testing. 
cart.AddLineItem(orderForm, lineItem, orderGroupFactory);

// Remove a line item from the first shipment on the first form. 
cart.GetFirstShipment().LineItems.Remove(lineItem);

// Remove a line item from the second shipment on the first form.
cart.GetFirstForm().Shipments.Last().LineItems.Remove(lineItem);

// Remove a line item from the first shipment on the second form (b2b).
cart.Forms.Last().Shipments.First().LineItems.Remove(lineItem);

Set billing and shipping addresses

The following example shows how to set billing and shipping addresses.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
var cart = orderRepository.LoadCart<ICart>(contactId, "Default");

var address = orderGroupFactory.CreateOrderAddress(cart);

// Use Id to reuse the address.
address.Id = "Billing";
cart.GetFirstForm().Payments.First().BillingAddress = address;

// Because an address with the ID "Billing" already exists, that address is reused instead of creating another one on the order.
var reuseOtherAddress = orderGroupFactory.CreateOrderAddress(cart);
reuseOtherAddress.Id = "Billing";
cart.GetFirstShipment().ShippingAddress = reuseOtherAddress;

// Use RegionName and RegionCode when working with US states.
address.RegionName = "California";
address.RegionCode = "CA";
address.CountryCode = "US";
address.CountryName = "United States";

Add notes to orders

The following example shows how to add notes to orders.

var orderRepository = ServiceLocator.Current.GetInstance<IOrderRepository>();
var orderGroupFactory = ServiceLocator.Current.GetInstance<IOrderGroupFactory>();
var contactId = PrincipalInfo.CurrentPrincipal.GetContactId();
var cart = orderRepository.LoadCart<ICart>(contactId, "Default");

var notes = cart.Notes;

var note = orderGroupFactory.CreateOrderNote(cart);
note.CustomerId = contactId;
note.Type = OrderNoteTypes.Custom.ToString();
note.Title = "Noted";
note.Detail = "Something should be noted.";
note.Created = DateTime.UtcNow;
notes.Add(note);

orderRepository.Save(cart);

CartHelper is dead, long live IOrderRepository