Hide menu Last updated: Oct 24 2016
Area: Episerver Commerce Applies to versions: 10 and higher
Other versions:

Order manipulation

This topic describes how to create, load, save and delete orders in Episerver Commerce.

How it works

When manipulating orders in Episerver Commerce, refer to the namespace EPiServer.Commerce.Order, specifically the classes EPiServer.Commerce.Order.IOrderRepositoryEPiServer.Commerce.Order.IOrderRepositoryExtensions, EPiServer.Commerce.Order.IOrderGroupExtensions, and EPiServer.Commerce.Order.IOrderGroupFactory.

Creating orders

When creating orders using the default implementation of IOrderGroupFactory, there is always an IOrderForm in the Forms collection. There is also always an IShipment on the Shipments collection of the IForm. If you create a custom IOrderGroupFactory, assume you need this as well.

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");

Loading orders

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

//loading cart will return 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 customer
var carts = orderRepository.Load<ICart>(contactId, "Default");

//load or create cart will create cart if does not exist
var cart = orderRepository.LoadOrCreateCart(contactId, "Default");

//loading wishlist will return null if 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 whishlists for customer
var wishlists = orderRepository.Load<ICart>(contactId, "Wishlist");

//load or create wishlist will create cart if does not exist
var wishlist = orderRepository.LoadOrCreateCart(contactId, "Wishlist");

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

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

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

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

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

Saving orders

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);

Deleting orders

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

Working with 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 new order form (b2b)
var orderForm = orderGroupFactory.CreateOrderForm(cart);
cart.Forms.Add(orderForm);
orderForm.Name = "Default";

//delete order form
cart.Forms.Remove(orderForm);

Working with 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");

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

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

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

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

Working with payments

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 payment to first form
var creditCard = orderGroupFactory.CreateCardPayment(cart);
var invoice = orderGroupFactory.CreatePayment(cart);
//pass in orderGroupFactory for unit testing as a from will be created if there is none on the cart.
cart.AddPayment(creditCard, orderGroupFactory);
cart.AddPayment(invoice, orderGroupFactory);
//Set address after adding to collection becasue of limitation in implementation
creditCard.BillingAddress = orderGroupFactory.CreateOrderAddress(cart);

//Create and add payment to 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 address after adding to collection becasue of limitation in implementation
creditCard.BillingAddress = orderGroupFactory.CreateOrderAddress(cart);

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

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

Working with line items

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 line item to first shipment on first form
var lineItem = orderGroupFactory.CreateLineItem("code", cart);

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

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

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

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

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

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

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

Working with 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
address.Id = "Billing";
cart.GetFirstForm().Payments.First().BillingAddress = address;

//Since there is already an address with "Billing" it will use that address instead of creating another one on the order.
var reuseOtherAddress = orderGroupFactory.CreateOrderAddress(cart);
reuseOtherAddress.Id = "Billing";
cart.GetFirstShipment().ShippingAddress = reuseOtherAddress;

//Region Name and Region Code should be used when dealing with states
address.RegionName = "California";
address.RegionCode = "CA";
address.CountryCode = "US";
address.CountryName = "United States";

Working with notes

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);

Comments

The IOrderRepository should be able to load all orders of a given type (Cart/PurchaseOrder/whatever) created since/between/before dates - regardless of user. Every function in the order repository now requires either exact order IDs or a user context. For reporting, batch jobs etc. this makes things unnecessarily complicated, and forces us to use the OrderContext class, which is a true pain.

We hear you. We already have a plan to add search support for the new abstraction APIs in our backlog - but it'll not happen anytime soon.