Product variants

This document describes how to work with product variants (also known as variations) in relation to the content model.

How it works

Product variants are represented by the EPiServer.Commerce.Linking.ProductVariation class and administered using the EPiServer.Commerce.Linking.ILinksRepository service.

The Target property of the ProductVariation contains the ContentReference of the variant. The class also has a SortOrder property describing the order of the variants and a GroupName property for grouping variants. The Quantity property is not used for variants. EPiServer.Commerce.Linking.EntryRelation contains default values that can be used: DefaultGroupName and DefaultQuantity.

A ProductVariation is uniquely defined by the ContentReference in its Target property together with its Source property (referencing the product that has the variant), i.e. the same variant can not be added more than once to a product.

Getting the variants for a product

By calling the GetRelationsBySource method of ILinksRepository with the ContentReference of a product, and filtering for ProductVariation you get the variants:

public IEnumerable<ProductVariation> ListVariations(ContentReference referenceToProduct)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();
    var allRelations = linksRepository.GetRelationsBySource(referenceToProduct);

    // Relations to Variations are of type ProductVariation
    var variations = allRelations.OfType<ProductVariation>().ToList();
    return variations;
}

Getting the product by variant

By calling the GetRelationsByTarget method of ILinksRepository with the ContentReference of a variant, and filtering for ProductVariation you get the products:

public IEnumerable<ProductVariation> GetProductByVariant(ContentReference variation)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();
    var allRelations = linksRepository.GetRelationsByTarget(variation);

    // Relations to Product is ProductVariation
    return allRelations.OfType<ProductVariation>().ToList();
}

Adding a variant to a product

The UpdateRelations method or UpdateRelation extension method of ILinksRepository can be used to add new ProductVariation objects to a product. The new variant has to have a Target ContentReference ana a Source ContentReference

public void AddVariation(ContentReference referenceToProduct, ContentReference referenceToVariation)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();

    var newVariation = new ProductVariation
    {
        SortOrder = 100,
        Source = referenceToProduct,
        Target = referenceToVariation
    };

    linksRepository.UpdateRelation(newVariation);
}

Removing variant from a product

By calling the RemoveRelations method or RemoveRelation extension method of ILinksRepository with a ProductVariation object matching an existing variant, that variant will be removed from the product. You can either construct a matching object, or use GetRelationsBySource to get the existing Relations, filter out the object you want to remove, and pass it to RemoveRelation.

public void RemoveVariation(ContentReference referenceToProduct, ContentReference referenceToVariation)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();

    // Define a relation matching the one to remove, or use
    // GetRelations to find the one you want to remove and pass that to
    // RemoveRelation
    var relationToRemove = new ProductVariation
    {
        // Source is required here to match the correct relation
        Source = referenceToProduct,
        Target = referenceToVariation
    };

    // Removes matching ProductVariation, or no action if no match exists
    linksRepository.RemoveRelation(relationToRemove);
}