The Different Ways Of Saving Content In Episerver Commerce

Trying to create, update and save objects in commerce can cause quite a lot of confusion. The confusion I generally see around the usage of Episerver commerce API is people using the wrong one and then wondering why it didn't work. In today's guide, I'm going to walk through the different API's that are available to us as developers.

Why So Many API's?

Episerver commerce has three different API's for dealing with different areas in commerce. We have:
  • The Catalog
  • Built in Episerver Objects
  • Custom Objects
If you look in Commerce Manager in the Administration section, you see these two folders: episerver_commerce_different_object_types This is a good visual example of the different area the API's focus split. When adding items into the catalog, the process works like the CMS as in it uses a typed content model. You create your own class and inherit from a commerce catalog type, you use the [CatalogContentType] attribute to decorate the class with the standard things like Name, Description, and GUID and then you implement the properties you want within the class itself. You can then use the normal CMS API's, IContentRepository or IContectLocator to query those objects. If you want some more information about the catalog then have a read now, The Different Ways Of Getting Items From The Catalog in Episerver Commerce. The new from commerce 7.5 up typed content model is based upon the older is Metadata Plus.

Built in Episerver Objects

Meta Data Plus is the original API for accessing a lot of commerce content. From Episerver Commerce 7.5 forwards, I would not recommend using Meta Data Plus for doing tasks such as adding and retrieving catalog items, as mentioned above use the typed content model approach instead. It's useful to know about Meta Data Plus (and Business Foundation, which we'll get to shortly) when you want to extend the out-of-the-box catalog/order metaclasses. Meta Data Plus allows the additional and extension of objects, or, as known in commerce 'Meta Class' by adding on extra properties, called 'Meta Fields'. So for example, to load a class from the database we would use code like this:
            var context = OrderContext.MetaDataContext;
            var metaClassName = "Contact";
            var metaClass = MetaClass.Load(context, metaClassName);
In this example, metaClassName would represent a table that existed in the Episerver commerce database. In this example 'Contact' is an Episerver out-the-box thing, that lives in the [cls_Contact] database table. The classes you can access via Meta Data Plus, include Contact, ContactNote, Address and Organization. In reality you probably won't touch this area of code too often... you will however, be a lot more likely to work with the newer Business Foundation Objects. More information about Meta Data Plus can be found in this guide, Meta Data Plus

Business Foundation Objects

If you want to work with your own objects with-in Episerver commerce, Business Foundation objects are your friends. Business Foundation Framework came slightly after Meta Data Plus but again is another API the works with objects within Episerver commerce. Business Foundation objects allow you to create new 'Meta Classes', which you can add fields to, with different data types. Like Meta Data Plus when you create a new class it will actually create a corresponding database entry in the commerce database. Any data you store will then be saved within this table. Business Foundation Objects and the Meta Data Plus are very similiar and I personally think it's a bit confusing when you're trying to figure out what API you need to use to do a task.. but moaning aobut it won't get us anywhere. The snippet below shows you how to query a business object called, Contact and then adds a custom property to it called "MiddleName".
    var metaModel = DataContext.Current.MetaModel;
    foreach (var metaClass in metaModel.MetaClasses)
        if (metaClass.Name == "Contact")
            var fieldName = "MiddleName";
            if (metaClass.Fields[fieldName] == null)
                var attr = new AttributeCollection();
                MetaField newMetafield = mc.CreateMetaField(

To access your business foundation objects, you can use the following MetaModel instance, to get access to all the business foundation objects in the system. This can be done using the following snippet:

A Word Of Caution

On one of my recent projects, one of the developers got quite confused between the two API's. If you use Business Foundation Objects API you can run into cross compatibility issuess, for example, in the diagram below: episerver_commerce_database_busines_foundations There are two different MetaClass tables, if you use a Meta Data Plus object its definition will be created in one table, if you use business foundation objects your class definition will be created in the other. I n the [MetaClass] table things like OrderForm, LineItem, and all your custom catalog definitions live . Items like Contact, Organization and Address live in the [mcmd_MetaClass] table. If you find yourself scratching your head why you can't access your data or you can't save an item correctly. The first thing you should do is make sure you are using the correct API to connect to it.

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