Markets

This document provides an overview of the Market concept in EPiServer Commerce, explaining what it means and how it can be used. The Market concept is central in this area of e-commerce, and means that you can define multiple markets, each with its own product catalog, language, currency, and promotions, for a single-site.

All classes referred to here are available in the Mediachase.Commerce or Mediachase.Commerce.Markets namespaces.

CurrentMarket interface

Sites implementing multi-market functionality must implement the ICurrentMarket interface. The ICurrentMarket implementation must return the market of the current request, and will be called to get the appropriate market for the execution of most market-sensitive business logic. Custom implementations of ICurrentMarket must be registered at the initialization step of the application by implementing IConfigurableModule.

A business's determination of their market segmentation strategy will determine their implementation of the ICurrentMarket interface. If a business segments markets geographically, they may wish to use a prestitial page, an IP geolocation service, or a simple dropdown control to determine a user's region and market.

Markets are not constrained to be regional; a business-to-business is likely to permit only authenticated users to use the system, and may assign a market to each customer when the customer is created. In this case, the ICurrentMarket implementation could retrieve the current market based on the current authenticated user.

The default, supplied implementation if ICurrentMarket will always return the default market. This is the correct behavior for sites that do not implement multi-market functionality.

The ICurrentMarket interface:

public interface ICurrentMarket
{
    // Gets the current market.
    IMarket GetCurrentMarket();
}

Example: Registering a custom ICurrentMarket implementation:

using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.Framework.ServiceLocation;
using Mediachase.Commerce;

// The custom implementation of ICurrentMarket
public class MyCurrentMarketImplementation : ICurrentMarket
{
    public IMarket GetCurrentMarket()
    {
        ... implementation ...
    }
}

[ModuleDependency(typeof(Mediachase.Commerce.Initialization.CommerceInitialization))]
[InitializableModule]
public class MyCurrentMarketModule : IConfigurableModule
{
    public void ConfigureContainer(ServiceConfigurationContext context)
    {
        context.Container.Configure(ce =>
        {
            ce.For<ICurrentMarket>().Singleton().Use<MyCurrentMarketImplementation>();                
        });
    }

    public void Initialize(InitializationEngine context) { }
    public void Preload(string[] parameters) { }
    public void Uninitialize(InitializationEngine context) { }
}

Market definition

A market is represented by an instance of the IMarket interface. The data associated with each market is typically used as a set of guidelines for regional markets, however the market system is not specifically tied to region; and languages and currencies will not be automatically filtered based on the value of the current market. The MarketImpl class may be used as a default implementation of the IMarket interface.

There will always be a default market, with ID MarketId.Default. This market may be disabled for sites implementing multi-market functionality, but should not be deleted.

The IMarket interface:

public interface IMarket
{
    // Gets the market's unique identifier.
    MarketId MarketId { get; }

    // Gets a value indicating if the the market is enabled.
    bool IsEnabled { get; }

    // Gets the market's name.
    string MarketName { get; }

    // Gets the default language for the market.
    CultureInfo DefaultLanguage { get; }

    // Gets the available languages for the market.
    IEnumerable<CultureInfo> Languages { get; }

    // Gets the default currency for the market.
    Currency DefaultCurrency { get; }

    // Gets the available currencies for the market.
    IEnumerable<Currency> Currencies { get; }

    // Gets the countries associated with the market.
    IEnumerable<string> Countries { get; }
}

Interacting with markets

Market data is accessed with the IMarketService API. This API exposes simple create/replace/update/delete operations for market data.

The IMarketService interface:

public interface IMarketService
{
    // Gets all markets in the system.
    IEnumerable<IMarket> GetAllMarkets();

    // Get a single market by ID, or null if the market ID is not found.
    IMarket GetMarket(MarketId marketId);

    // Adds a new market to the market system.
    void CreateMarket(IMarket market);

    // Updates an existing market in the market system.
    void UpdateMarket(IMarket market);

    // Deletes a market by ID.
    void DeleteMarket(MarketId marketId);
}

Markets, orders, carts, and wishlists

To enable processing when the ICurrentMarket implementation may not be available, orders, carts, and wishlists include a market ID.

Since carts are market-dependent, carts will be unique to a user and market, instead of just the user. If a site permits a user to switch their market, then switching the market may also switch any carts to a new or different carts. Since wishlists are carts, this paragraph also applies to wishlists.