The Different Ways Of Getting Items From The Catalog in Episerver Commerce

When you start working with Episerver commerce, you might become overwhelmed with the number of API's available to you.  Finding the right API to do the task at hand can be a frustrating and a time-consuming exercise at times.  The Episerver SDK does hold a lot of information but it can be a bit patchy and vague at times.  I've definitely lost my patience a few times trying to figure out how to do some simple task.  The aim of today's guide is to try and explain some of the API's available to you for working with items that live within your PIM (Product Information Management) / Commerce Catalog.

The Catalog

When you work on an e-commerce project with Episerver commerce, you will need to work with the items within your PIM a lot.  These will include the standard things like creating a folder to add a product, getting data to display a product on your website, getting an item to add to a basket or even associate a product with a designated category.  In Episerver terminology, the items you will be working with are VariationContent, ProductContent, BundleContent, PackageContent and NodeContent. More information about these types can be found here.  In basic terms, VariationContent and ProductContent are your products and NodeContent are folders you can create in your catalogue.  I'll ignore the other types for this article but it can be handy to know they exist.

IContentRepository or IContentLoader

If you have worked with the Episerver CMS before, it is very likely that you will be familiar with the IContentRepository API.  The Content Repository is the API you need to use to get the data about your products and variants from Episerver. The content repository is pretty easy to work with, with the standard Load and Save methods. I've talked about the IContentRepository before quite a lot and if you want to see some code examples of how it works, I suggest you have a look at these posts How To Load And Retrieve A Variant or Product From Episerver Commerce and How To Get a Catalogue in Episerver Commerce If you are confused about the difference between IContentRepository or IContentLoader, IContentLoader is a read-only version. IContentRepository allows you to do things like Delete and Save. Behind the scenes, IContentRepository will call IContentLoader, and performance-wise, there isn't really a massive hit between the two. Due to this, I generally tend to favour using IContentRepository because as your code base grows, if you suddenly decide you need IContentRepository you may have to refactor a number of unit tests when you could have just used IContentRepository in the first place.

Reference Converter

The reference converter is a very simple API but is very useful when working with Episerver commerce. In a lot of circumstances, you may only have your products SKI (Stock Control Identifier), or, in Episerver terminology, the products 'Code'. The reference converter takes in this string value and returns you a reference to the matching Episerver object. Remember all codes need to be unique within the catalogue.

var referenceConverter = ServiceLocator.Current.GetInstance<ReferenceConverter>();
var code = "variant-code"; 
var variantLink = referenceConverter.GetContentLink(code );

Warning: The reference converter talks to the database directly and does not work with a cache.  For this reason, it is important to get the architecture for your website correct so you do not have to repeatedly make unneeded database calls when you're rendering pages.


Up until how we've been dealing with API's at a very high level of abstractions of the nice classes we've designed for the system. The CatalogContext takes us down a notch and works on the DataTable and generic DTO level catalogue; for example at this level, instead of working with an actual product we have defined in the code, we work with a generic CatalogEntryDto. Working at this level, you get access to a few things the IContentRepository doesn't provide. It also allows you to work more with the relationships and associations between the objects. The CatalogContext is similar to the Episerver Data Provider whereas they both make use of the singleton pattern. The downside of this approach is that it makes it very hard to unit test your code. This is why if you have access to the newer versions of commerce I would always recommend working with IContentRepository and the ILinksRepository/ The code to get a product can be seen below:

     var catalogEntryDto = CatalogContext.Current.GetCatalogEntryDto("PRODUCT_CODE",
                  new CatalogEntryResponseGroup(CatalogEntryResponseGroup.ResponseGroup.CatalogEntryInfo));

To get a node

     varcatalogNodeDto = CatalogContext.Current.GetCatalogNodeDto("NODE_CODE",
                 new CatalogNodeResponseGroup(CatalogNodeResponseGroup.ResponseGroup.CatalogNodeInfo));


The links repository is one of the newer Episerver Commerce API's, available from version 7.5 onwards.  The links repository is the place to look for handling catalogue relations and associations; for example, if you want to change the parent of a node, or, add an association (link) from a variant to a catalogue this is the API for you. As the repository works via an interface it's all unit testable which is nice.

var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();
                var linkedEntry = new NodeRelation()
                    SortOrder = 0,
                    Source = entryLink,
                    Target = categoryLink,


In today's guide, we've introduced and hopefully explained the API's you will need to use when dealing with objects within the Episerver commerce catalogue. There is a number of older and new API's available to you, depending on which version of Episerver commerce you will be working with. If possible, use the newer API's that use the ServiceLocator. Using these API's will allow you to unit test your code. Here are some basic dos and don'ts:

  • Use IContentRepository when you want to access your product data
  • Use ILinksRepositorywhen you want to play with the associations of objects within your catalogue
  • Use CatalogContext when you want to work with a lower level of abstraction within your catalogue
  • Use ReferenceConverter to get an Episerver reference based on a product code

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