Episerver Commerce The Purchase Order Object Explained

In today's guide, I'm going to cover the build in Episerver purchase order object.  For those new to commerce, the purchase order is the object where you save all the information about the order at the place of purchase.  After the user has paid, all the information about the order needs to be stored in a format that won't change. I worked on a recent commerce project where the solution used a third party order system to place orders.  In this scenario, the developer in question was still using the cart and the line items to populate the order document. I find this architecture approach very flawed.  If the cart or the line items change from the time the system gets the payment provider authorization/capture to the moment in this scenario the order system was called, then in the worst case scenario the user might get charged x amount and the confirmation page and email etc.. that was implemented to use the cart and line-items If you are implementing a new commerce project then I would strongly recommend that, on the moment the payment has been captured, you save everything you need in the purchase order and clear the cart.  Doing this forces any developers to use the correct object rather than using the wrong objects and risk introducing bugs that might make the user see out of date. If the purchase order object does not have the fields you need, you can either add them in manually via commerce. Personally, I don't like this approach.  Instead, I like to add new fields in code.  This way I can guarantee that no typos happen and I can clean my database and rebuild the database easily. If you need some more information about how to do this then I would recommend reading, How To Add A Custom Property To The Purchase Order in Episerver Commerce.

How To Get A Purchae Order From Episerver

To get a purchase order from Episerver is pretty simple:
   var purchaseOrder = PurchaseOrder.LoadByOrderGroupId(orderId);
In this code we use the PurchaseOrder helper in the Mediachase.Commerce, Mediachase.Commerce.Orders namespace.  In here you can pass in the cart or order group provider Id. The PurchaseOrder allows you to do the usual suspects of operations like UpdateShipmentLineItemQuantity, Search, RemoveLineItemFromShipment etc.. There is also an alternative way to get Purchase Order information from commerce.  I definitely wouldn't recommend using this approach, as it requires a lot more code and will likely break in future versions, however, it may come in useful I guess?
            var parameters = new OrderSearchParameters();
            var options = new OrderSearchOptions
                CacheResults = false,
                RecordsToRetrieve = 1,
                StartingRecord = 0,
                Classes = new StringCollection { "PurchaseOrder" },
                Namespace = "Mediachase.Commerce.Orders"
            parameters.SqlMetaWhereClause = string.Format("Meta.OrderId LIKE '{0}'", orderId);
            var order = OrderContext.Current.FindPurchaseOrders(parameters, options).FirstOrDefault();
The code above uses a pretty old school hacky way.  You create some OrderSearchOptions and OrderSearchParameters. Manually define some SQL in code (yuk!) and they pass the objects into the OrderContext.Current.FindPurchaseOrders() method to get the purchase order.  Again, I would not advise you to use this but if you come across this in an old project when you upgrade, remember there are a lot easier ways to get purchase order information.

Creating A Purchase Order

To create a new purchase order within Episerver is also pretty simple in the latest versions of commerce.  The easiest option is to use the 'IOrderRepository'
     Mediachase.Commerce.Orders.Cart cart;

     var repository = ServiceLocator.Current.GetInstance<IOrderRepository>();
     var orderReference = repository.SaveAsPurchaseOrder(cart);


In today's guide, I've talked about the in-built purchase order object.  In Episerver commerce, this is the object you need to talk to when you're working with after sales data.  My advice would be to store all the information you care about in the purchase order and clear the current users cart as soon as they purchase to prevent random bugs being introduced into your code base.  You can do the standard CRUD type of operations using the PurchaseOrder API and should be your first port of call when you want to work with purchase order objects,

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

Back to top
var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-35662136-1']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'stats.g.doubleclick.net/dc.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })();