In this tutorial, you will learn about the Episerver Commerce purchase order object, what it is and what it does. In any E-Commerce website, after a customer has added products into the basket, gone through checkout and paid, you will need a mechanism to persist all of their order data back into the Episerver Commerce database in a format that won't change. This is where the purchase order object comes into play. If you would like to learn more about how to save data on purchase, read on 🔥🔥🔥
One important consideration when building any commerce website is data consistency. If you are implementing a new commerce project, I would strongly recommend that as soon as the order payment has been captured and confirmed, you save all the order data in the purchase order and then clear the customer's cart straight away. A major anti-pattern within Episerver Commerce is to carry on using the cart object and the line item object after an order has been completed. Both the cart and the line item objects can change after purchase. Using either of these items after purchase means you run the risk that basket data and the order data differ. This is why you need to create a purchase order object as soon as you get payment confirmation. Without doing this, it is possible to have a discrepancy between the cart data and what the customer paid for. If this happened on hundreds of orders, this would not be a good situation 😞
Creating and using the purchase order as soon as possible in the checkout flow will ensure the developers are using the correct data. After checkout, it is easy to use the wrong objects and risk introducing bugs using stale data. This is why I recommend wiping the cart object. Clearing the objects you should no longer use, guarantees that the team can not accidentally use the wrong objects 🤔
To ensure you create a valid timestamped version of your order data within the purchase order table, you will need to ensure the purchase object contains all the fields required to process that order. As a developer, it is possible to shape and refine the purchase order object to suit your project needs. You can add properties on the purchase order object manually via the Episerver Commerce UI, or using code. Personally, I like to add new fields in code within a start-up script to ensure repeatability. Using code to define the database changes means I can reset my database and rebuild the project from scratch easily if needed.
If you want to learn how to update the purchase order in code, I would recommend reading, How To Add A Custom Property To The Purchase Order in Episerver Commerce.
How To Get A Purchase Order From Episerver
To query the Episerver Commerce database to get a purchase order from Episerver is pretty simple, as shown below:
To access a purchase order, you use the PurchaseOrder helper. This helper is found in the Mediachase.Commerce, Mediachase.Commerce.Orders namespace. Pass in the cart object or OrderGroupProviderId into LoadByOrderGroupIdand and the API will return a matching purchase order object if applicable. The PurchaseOrder helper allows you to do the usual CRUD type of operations, like UpdateShipmentLineItemQuantity, Search, andRemoveLineItemFromShipment.
There is an alternative way to get purchase order information from Episerver Commerce. I do not recommend using this approach, however, knowing about it will deepen your knowledge of Episerver Commerce. This alternative approach will result in you writing more code and the API is likely to be deprecated in future versions, so be warned ⚠️
The code above is less intuitive and less declarative to understand. You create some OrderSearchOptions and OrderSearchParameters. Manually define some SQL in code (yuk!) and pass the parameters into the OrderContext.Current.FindPurchaseOrders() method. FindPurchaseOrders() will return a populated purchase order object if applicable. Again, I would not advise you to use approach unless you encounter some strange bug in your code with the more modern API 🤔
Creating A Purchase Order
Creating a new purchase order within Episerver is also pretty simple. As of Episerver Commerce 8, the easiest option is to use the IOrderRepository API. Creating a new order can be done using this code:
Taking the Cart object, you can use SaveAsPurchaseOrder(). This will return the purchase order Id, which you can then use 💥
You are now a master of the Episerver Commerce in-built purchase order object <(°.°)>. In Episerver commerce, the purchase order object is the mechanism to save and retrieve after sales data. My advice would be to store all the information you care about in the purchase order and clear the current user's cart as soon as possible to prevent random bugs from being introduced into your codebase. Happy Coding 🤘
