Commerce Catalog API Reference
Corecommerce
Overview
Section titled “Overview”The Catalog API provides programmatic access to catalog structures including catalogs, categories (nodes), products (entries), and variants. The primary entry points are ICatalogSystem, IContentRepository, and ReferenceConverter.
Namespace
Section titled “Namespace”Optimizely.Commerce.Catalog
Key interfaces
Section titled “Key interfaces”| Interface | Purpose |
|---|---|
ICatalogSystem | Low-level catalog operations (legacy) |
IContentRepository | Content-based catalog CRUD (recommended) |
ReferenceConverter | Converts between catalog entry codes and ContentReference |
IRelationRepository | Manages parent-child and variant relationships |
ICatalogImportExport | Bulk import/export operations |
ReferenceConverter
Section titled “ReferenceConverter”Converts between catalog entry/node codes and CMS content references.
| Method | Returns | Description |
|---|---|---|
GetContentLink(string code) | ContentReference | Resolves a catalog code to a content reference |
GetContentLink(int entryId, CatalogContentType) | ContentReference | Resolves by entry ID and type |
GetCode(ContentReference) | string | Returns the catalog code for a content reference |
Catalog entry types
Section titled “Catalog entry types”| Type | Base class | Description |
|---|---|---|
| Product | ProductContent | Top-level purchasable item with variants |
| Variation | VariationContent | Specific SKU with price and inventory |
| Package | PackageContent | Bundle of entries sold as one SKU |
| Bundle | BundleContent | Collection of entries sold individually |
Loading catalog content
Section titled “Loading catalog content”Get<T>(ContentReference)
Section titled “Get<T>(ContentReference)”Loads a single catalog entry or node.
Parameters
| Name | Type | Description |
|---|---|---|
contentLink | ContentReference | Reference to the catalog content |
Returns: T where T is a catalog content type
Throws: ContentNotFoundException if the reference does not exist
Load a product by code
public class CatalogService
{
private readonly IContentRepository _contentRepo;
private readonly ReferenceConverter _referenceConverter;
public CatalogService(
IContentRepository contentRepo,
ReferenceConverter referenceConverter)
{
_contentRepo = contentRepo;
_referenceConverter = referenceConverter;
}
public ProductContent GetProduct(string code)
{
var contentLink = _referenceConverter.GetContentLink(code);
return _contentRepo.Get<ProductContent>(contentLink);
}
}GetChildren<T>(ContentReference)
Section titled “GetChildren<T>(ContentReference)”Returns immediate children of a catalog node.
Parameters
| Name | Type | Description |
|---|---|---|
parentLink | ContentReference | Reference to the parent node or catalog |
Returns: IEnumerable<T>
List products in a category
var categoryRef = _referenceConverter.GetContentLink("tops-category");
var products = _contentRepo.GetChildren<ProductContent>(categoryRef);
foreach (var product in products)
{
Console.WriteLine($"{product.Code}: {product.DisplayName}");
}Creating catalog content
Section titled “Creating catalog content”GetDefault<T>(ContentReference)
Section titled “GetDefault<T>(ContentReference)”Creates a new default instance under a parent node.
Parameters
| Name | Type | Description |
|---|---|---|
parentLink | ContentReference | Parent node or catalog root |
Returns: T — writable content instance
Save(IContent, SaveAction, AccessLevel)
Section titled “Save(IContent, SaveAction, AccessLevel)”Persists catalog content to the database.
Parameters
| Name | Type | Description |
|---|---|---|
content | IContent | The catalog content to save |
action | SaveAction | Publish, CheckIn, Save |
access | AccessLevel | Access level check; use AccessLevel.NoAccess to skip |
Returns: ContentReference
Create a new product
var categoryRef = _referenceConverter.GetContentLink("tops-category");
var product = _contentRepo.GetDefault<FashionProduct>(categoryRef);
product.Code = "SHIRT-001";
product.DisplayName = "Classic Oxford Shirt";
product.Name = "Classic Oxford Shirt";
_contentRepo.Save(product, SaveAction.Publish, AccessLevel.NoAccess);Variant relationships
Section titled “Variant relationships”IRelationRepository
Section titled “IRelationRepository”Manages product-to-variant and bundle relationships.
| Method | Returns | Description |
|---|---|---|
GetRelationsBySource<T>(ContentReference) | IEnumerable<T> | Gets relations where this entry is the source |
GetRelationsByTarget<T>(ContentReference) | IEnumerable<T> | Gets relations where this entry is the target |
UpdateRelation(ContentRelation) | void | Adds or updates a relation |
RemoveRelation(ContentRelation) | void | Removes a relation |
Get variants for a product
public IEnumerable<VariationContent> GetVariants(ContentReference productLink)
{
var relations = _relationRepo
.GetRelationsBySource<ProductVariation>(productLink);
return relations
.Select(r => _contentRepo.Get<VariationContent>(r.Target));
}Deleting catalog content
Section titled “Deleting catalog content”Delete(ContentReference, bool)
Section titled “Delete(ContentReference, bool)”| Name | Type | Description |
|---|---|---|
contentLink | ContentReference | Reference to catalog content |
forceDelete | bool | true = permanent delete, false = soft delete |
Throws: AccessDeniedException if the user lacks delete permissions
Common exceptions
Section titled “Common exceptions”| Exception | Cause |
|---|---|
ContentNotFoundException | Content reference does not resolve |
AccessDeniedException | Insufficient permissions for the operation |
ValidationException | Required fields missing or code already exists |
CatalogCodeAlreadyExistsException | Duplicate catalog entry code |