Umbraco Commerce
CMSCloudHeartcoreDXP
15.latest
15.latest
  • Umbraco Commerce Documentation
  • Release Notes
    • v15.1.0-Rc
    • v15.0.0-Rc
  • Commerce Products
    • Commerce Packages
    • Commerce Payment Providers
    • Commerce Shipping Providers
  • Getting Started
    • Requirements
    • Installation
    • Licensing
    • Configuration
    • User Interface
  • Upgrading
    • Upgrading Umbraco Commerce
    • Version Specific Upgrade Notes
    • Migrate from Vendr to Umbraco Commerce
      • Migrate Umbraco Commerce Checkout
      • Migrate custom Payment Providers
  • Tutorials
    • Build a Store in Umbraco using Umbraco Commerce
      • Installation
      • Creating a Store
        • Configuring your Store
      • Creating your first Product
      • Implementing a Shopping Cart
        • Using the Umbraco.Commerce.Cart Drop-in Shopping Cart
        • Creating a Custom Shopping Cart
      • Implementing a Checkout Flow
        • Using the Umbraco.Commerce.Checkout Drop-in Checkout Flow
        • Creating a Custom Checkout Flow
      • Configuring Store Access Permissions
  • How-To Guides
    • Overview
    • Configure SQLite support
    • Use an Alternative Database for Umbraco Commerce Tables
    • Customizing Templates
    • Configuring Cart Cleanup
    • Limit Order Line Quantity
    • Implementing Product Bundles
    • Implementing Member Based Pricing
    • Implementing Dynamically Priced Products
    • Implementing Personalized Products
    • Implementing a Currency Switcher
    • Building a Members Portal
    • Order Number Customization
    • Create an Order via Code
  • Key Concepts
    • Get to know the main features
    • Base Currency
    • Calculators
    • Currency Exchange Rate Service Provider
    • Dependency Injection
    • Discount Rules / Rewards
    • Events
      • List of validation events
      • List of notification events
    • Fluent API
    • Order Calculation State
    • Payment Forms
    • Payment Providers
    • Pipelines
    • Price/Amount Adjustments
    • Price Freezing
    • Product Adapters
    • Product Bundles
    • Product Variants
      • Complex Variants
    • Properties
    • ReadOnly and Writable Entities
    • Sales Tax Providers
    • Search Specifications
    • Settings Objects
    • Shipping Package Factories
    • Shipping Providers
    • Shipping Range/Rate Providers
    • Tax Sources
    • UI Extensions
      • Analytics Widgets
      • Entity Quick Actions
      • Order Line Actions
      • Order Properties
      • Order Collection Properties
      • Order Line Properties
      • Store Menu Items
    • Umbraco Properties
    • Unit of Work
    • Umbraco Commerce Builder
    • Webhooks
  • Reference
    • Stores
    • Shipping
      • Fixed Rate Shipping
      • Dynamic Rate Shipping
      • Realtime Rate Shipping
    • Payments
      • Configure Refunds
      • Issue Refunds
    • Taxes
      • Fixed Tax Rates
      • Calculated Tax Rates
    • Storefront API
      • Endpoints
        • Order
        • Checkout
        • Product
        • Customer
        • Store
        • Currency
        • Country
        • Payment method
        • Shipping method
        • Content
    • Management API
    • Go behind the scenes
    • Telemetry
Powered by GitBook
On this page
  • Example Product Adapter
  • Support editable carts
  • Registering a Product Adapter

Was this helpful?

Edit on GitHub
Export as PDF
  1. Key Concepts

Product Adapters

Converting product sources into understandable products for Umbraco Commerce.

The role of a Product Adapter in Umbraco Commerce is to provide an interface between a product information source and convert it into a standardized format. This is done to prevent the need for Umbraco Commerce to be tied to that source.

What this means for developers is that Product Adapters allow you to hook in alternative product information sources that may not be Umbraco node-based. You may hold your product information in a third-party database table. A custom Product Adapter would then allow Umbraco Commerce to interface with that custom data in the same way it would the default Umbraco node data.

Example Product Adapter

An example of a Product Adapter would look something like this:

public class MyCustomProductAdapter : IProductAdapter
{
    public Task<IProductSnapshot> GetProductSnapshotAsync(string productReference, string languageIsoCode)
    {
        // Lookup a product by productReference and convert to IProductSnapshot
    }

    public Task<IProductSnapshot> GetProductSnapshotAsync(string productReference, string productVariantReference, string languageIsoCode)
    {
        // Lookup a product by productVariantReference and convert to IProductSnapshot
    }

    Task<Attempt<(string ProductReference, string ProductVariantReference)>> TryGetProductReferenceAsync(Guid storeId, string sku)
    {
        // Try lookup a product / variant reference by store + sku
    }
}

All Product Adapters implement the IProductAdapter interface which requires three method implementations:

  • Two GetProductSnapshotAsync methods that retrieve a Product Snapshot for either a product or product variant by reference parameters.

  • A TryGetProductReferenceAsync method which retrieves a product/variant reference for a product that belongs to a given storeId and has the given sku.

A Product Snapshot consists of the following properties in order to present a Product to Umbraco Commerce in a standard way.

public interface IProductSnapshot
{
    // The unique reference for the product
    string ProductReference { get; }

    // The unique reference for the variant (if this is a variant snapshot)
    string ProductVariantReference { get; }

    // The unique SKU for this product/variant
    string Sku { get; }

    // The name of this product/variant
    string Name { get; }

    // The ID of the store this product/variant belongs to
    Guid StoreId { get; }

    // An optional Tax Class ID for this product/variant
    Guid? TaxClassId { get; }

    // Any properties exposed by this product/variant that should be copied to the orderline
    IDictionary<string, string> Properties { get; }

    // Any variant attributes for this product (if this is a variant snapshot)
    IEnumerable<AttributeCombination> Attributes { get; }

    // The available prices for this product/variant
    IEnumerable<ProductPrice> Prices { get; }

    // Flag indicating whether this product is a gift card product
    bool IsGiftCard { get; }
}

Support editable carts

To allow Umbraco Commerce to search for products/variants to add to a cart via the backoffice, Product Adapters can implement 3 additional methods. This can also be done to support editable carts.

public class MyCustomProductAdapter : ProductAdapterBase
{
    ... 

    public override Task<PagedResult<IProductSummary>> SearchProductSummariesAsync(Guid storeId, string languageIsoCode, string searchTerm, long currentPage = 1, long itemsPerPage = 50)
    {
        // Search for products matching the given search term and convert to a IProductSummary
    }

    public override Task<IEnumerable<Attribute>> GetProductVariantAttributesAsync(Guid storeId, string productReference, string languageIsoCode)
    {
        // Lookup the in-use product attributes of a primary product
    }

    public override Task<PagedResult<IProductVariantSummary>> SearchProductVariantSummariesAsync(Guid storeId, string productReference, string languageIsoCode, string searchTerm, IDictionary<string, IEnumerable<string>> attributes, long currentPage = 1, long itemsPerPage = 50)
    {
        // Search for product variants matching the given search term and/or the given attributes and convert to a IProductVariantSummary
    }
}

The IProductSummary, Attribute and IProductVariantSummary consists of the following properties in order to present a Product to Umbraco Commerce in a standard way.

public interface IProductSnapshot
{
    // The unique reference for the product
    string Reference { get; }

    // The unique SKU for this product 
    string Sku { get; }

    // The name of this product 
    string Name { get; }

    // The available prices for this product 
    IEnumerable<ProductPrice> Prices { get; }

    // Flag indicating whether this product has variants
    bool HasVariants { get; }
}

public class Attribute 
{
    // The alias of the attribute
    public string Alias { get; }

    // The name of the attribute
    public string Name { get; }

    // The attribute values
    IEnumerable<AttributeValue> Values { get; }
}

public class AttributeValue
{
    // The alias of the attribute value
    public string Alias { get; }

    // The name of the attribute value
    public string Name { get; }

}

public interface IProductVariantSnapshot
{
    // The unique reference for the product variant
    string Reference { get; }

    // The unique SKU for this product variant
    string Sku { get; }

    // The name of this product variant
    string Name { get; }

    // The available prices for this product variant
    IEnumerable<ProductPrice> Prices { get; }

    // The collection of attribute alias pairs of this product variant
    IReadOnlyDictionary<string, string> Attributes { get; }
}

Registering a Product Adapter

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyServices(IUmbracoCommerceBuilder builder)
    {
        // Replacing the default Product Adapter implementation
        builder.Services.AddUnique<IProductAdapter, MyCustomProductAdapter>();

        // Return the builder to continue the chain
        return builder;
    }
}
PreviousPrice FreezingNextProduct Bundles

Last updated 1 month ago

Was this helpful?

typeProduct Adapters are interface using the AddUnique<IProductAdapter, TReplacementAdapter>() method on the Services property. The TReplacementAdapter parameter is the type of our custom Product Adapter implementation.

registered via the IUmbracoCommerceBuilder