Area: Optimizely Commerce
Applies to versions: 14 and higher

Option configuration classes

Recommended reading 

This topic provides and overview of the various configuration possibilities and their settings, available in Optimizely Commerce. 

In this topic

How it works

The configuration options described in the following can all be set from appsettings.json, or through code using .NET 5 (Core) Configure<TOptions> in the ConfigureServices method of Startup.cs.

Note: Cache expiration variables in Options classes are defined as TimeSpan struct. You can override them with your own representation of TimeSpan struct for cache settings but be cautious of the performance affect it can have on your site.


This contains settings for handlers and plug-in collections for meta classes. The ConfigureServices method can be used to to add or remove handlers or plugins. See Working with entity objects.

services.Configure<BusinessManagerOptions>(o =>
    o.Handlers.Add(new CustomRequestHandler(){});
    o.Plugins.Add(new CustomRequestPlugin(){});
Name Description Default
Handlers Gets or sets handlers used in BusinessManager request processing. EPiServer specified handlers.
Plugins Gets or sets plugins used in BusinessManager request processing. EPiServer specified plugins.


Contains a set of meta object-related settings.

Name Description Default
MaxListObject Gets or sets the max list object, for example records to retrieve from meta object system while querying. 1000
UseCache Gets or sets a value indicating whether cache should be used while querying. false
CacheItemExpiration Gets or sets the cache item expiration in seconds. 30
UseSPOptimization Gets or sets a value indicating whether [use sp optimization]. false
SPItemExpiration Gets or sets the SP item expiration in minutes. 10080
Instances Gets or sets the business object services; list of MetaObjectInstance objects. Empty
Types Gets or sets the types; List<MetaObjectType> Empty


Contains a set of meta data-related settings.

Name Description Default
CacheExpiration The default expiration time. 10 minutes
DisableVersionSync Gets the value of the DisableVersionSync appSetting, indicating whether an update to Catalog content done outside the Content APIs will remove any version data (for example drafts, old published versions) for the affected Content. Setting this to "true" can improve the speed of batch operations done through the lower-level API:s like ICatalogSystem, in for example the catalog import. false
AllowUntypedCatalogContent Allows for no models to need to exist for catalog content. false
RemoveOrphanedMetaKeysBatchSize Batch size for remove orphaned key job. 10000


Contains settings for the Catalog subsystem. The CatalogOptions cache can be set via appsettings.json using the following syntax.

    "Commerce": {
        "CatalogOptions": {
            "Cache": {
                "UseCache": false
                "ContentVersionCacheExpiration": "1.02:03:04" //1 day, 2 hours, 3 mins, 4 seconds
            "SalePriceTypes": [{
                    "Key": "AllCustomers",
                    "Value": 0,
                    "Description": "Description",
                    "ControlUrl": "ControlUrl"
Name Description Default
AutoConfigure Determines whether to auto configure the Catalog system when first initialized. true
Cache Contains options for the catalog cache system. Instance of CatalogCacheOptions. See CatalogCacheOptions
SalePriceTypes Represents configures SalePriceTypes; List<SalePriceTypeDefinition> Empty
ShowVariationListPrice Enables the display of the obsolete variation list price in the catalog entry edit user interface false
CatalogImportBatchSize Gets or sets the batch size of the entries when importing a catalog. 200
CommandTimeout Gets or sets a value indicating whether to user custom sql command timeout or not in seconds. -1
CatalogEventLevel Used to control which events will be raised remotely. CatalogEventLevel.All
DisableCatalogEventDrivenIndexing Disables event indexing for the Commerce search provider not Search & Navigation (Find). false
SkipCatalogContentModelCheck Disables validating models exist in application domain. false
IgnorePropertyAndMetafieldMisMatch Ignores Meta field mismatches in catalog content scanning. false
SimplifiedCatalogListingThreshold Number of records which the catalog listing view does not group products and variants. 2000
DraftMigrationBatchSize Batch size when migrating legacy drafts to the new version store. 5000
DraftMigrationTimeSpan Timeout for draft store migration from legacy to new version store in hours. 1


Contains settings for the Catalog subsystem caching.

Name Description Default
UseCache Indicates if the cache is enabled. true
ContentVersionCacheExpiration Expiration time for catalog content versions. 10
CollectionCacheExpiration Expiration time for catalog relations, catalog associations, catalog nodes, catalog entries, catalog, tax categories and merchants. 15
EntryCacheExpiration Expiration time for entries. 15
NodeCacheExpiration Expiration time for nodes. 15
CurrencyCacheExpiration Expiration time for currencies. 1 hour
IdentityResolverCacheExpiration Expiration time for the identity resolver. 10
InventoryCacheExpiration Expiration time for inventory. 5
PriceCacheExpiration Expiration time for price. 10
PriceDetailsCacheExpiration Expiration time for price details. 10


Contains settings for URI validation, see Routing.

Name Description Default
UseLessStrictEntryUriSegmentValidation Gets the value of  episerver:commerce.UseLessStrictEntryUriSegmentValidationAppSetting, indicating whether validation of entry uri segments should be strict or not.

Strict validation means uri segments must be globally unique (for the language) to make sure all hierarchical routes to entries will work despite any crosslinking that happens after the uri segment has been saved.

With less strict validation, the uri segment will still be validated for uniqueness against sibling items, but since this happens at the time of saving, crosslinking items can create collisions in hierarchical routes.


Contains non-feature specific settings. To disable a feature, use the syntax as in the following example for serialized carts.

    "Commerce": {
        "ApplicationOptions": {
            "Features": {
                "SerializedCarts": {
                    "Feature": "SerializedCarts",
                    "State": 1, // 0 is enabled, 1 for disabled
                    "Type": "Mediachase.Commerce.Core.Features.SerializedCarts, Mediachase.Commerce"
Name Description Default
DefaultApplicationName Defines default value used for the application name. "ECApplication"
Cache Cache settings for the application. See ApplicationCacheOptions
AutoMigrate Auto-migrate Commerce. true
Roles Application roles. Key/value dictionary. EPiServer-specified default roles.
Features Configurable application features; SerializedCarts (enabled), WorkflowsVNext(disabled). N/A


Contains settings for Application-related caching.

Name Description Default
Enabled Determines whether in-memory caching is enabled or not. true


Contains settings for the Customers subsystem.

Name Description Default
AutoInstall Gets a value indicating whether to automatically install metadata definitions for entities related to customers/contacts. true
DemoInstall Gets a value indicating whether to automatically install sample customers in the system. true
Cache Config settings which define where caching is enabled and timeouts related to it. See CustomerCacheOptions


Contains settings for the Customers subsystem caching.

Name Description Default
UseCache Gets or sets if the cache is enabled. true
ContactCollectionCacheExpiration Gets or sets the contact collection expiration time. 1 minute
ContactCacheExpiration Gets or sets the contact expiration time. 1 minute
AddressCollectionCacheExpiration Gets or sets the address collection expiration time. 1 minute
AddressCacheExpiration Gets or sets the address expiration time. 1 minute
CreditCardCollectionCacheExpiration Gets or sets the credit card collection expiration time. 1 minute
OrganizationCollectionCacheExpiration Gets or sets the organization collection expiration time in minutes. 1 minute
OrganizationCacheExpiration Gets or sets the organization expiration time. 1 minute


Contains settings for data index management.

Name Description Default
DisableRetryPolicy Disabled the retry policy for the sql data provider. false
LowFragmentationThreshold Used by the maintain database indexes job. 10
HighFragmentationThreshold Used by the maintain database indexes job. 30
DataBaseIndicesJobCommandTimeOut Used by the maintain database indexes job. -1 for no timeout


Contains settings for the Markets subsystem.

Name Description Default
CacheExpiration The default expiration time used in MarketService. 5 minutes


Contains settings for the Orders subsystem.

Name Description Default
NewOrderStatus Gets the new order status. InProgress
AutoConfigure Gets a value indicating whether to auto-configure the Order system when first initialized. true
ShipmentAutoReleaseTimeout Gets or sets the shipment auto-release timeout. 1 day
DisableOrderDataLocalization Flag to indicate if order data localization is disabled. false
MetaClasses Contains the names of meta classes for orders that are stored in the configuration file. EPiServer-defined meta classes.
MappedTypes Gets the mapping of order-related entities to actual implementation classes. EPiServer-defined mapped types.
Cache The cache options for Orders. See OrderCacheOptions


Contains settings for the Order subsystem caching.

Name Description Default
UseCache Indicates if the cache is enabled. true
IsOrderRepositoryCacheDisabled Indicates if the order repository cache is disabled. false
JurisdictionCacheExpiration Expiration time for jurisdictions. 1 hour
TaxCacheExpiration Expiration time for taxes. 1 hour
CountryCacheExpiration Expiration time for countries. 1 hour
PaymentCacheExpiration Expiration time for payments. 1 day
ShippingCacheExpiration Expiration time for shipping. 1 day
StatusCacheExpiration Expiration time for status. 10 seconds
PickListCacheExpiration Expiration time for pick lists. 20 seconds
OrderCacheExpirationLegacy Expiration time for legacy ordergroups. 10 minutes
OrderCacheExpiration Expiration time for ordergroups. 10 minutes
UserOrderCacheExpiration Expiration time for user order. 5 minutes


Contains settings for the legacy Marketing subsystem (replaced by the new Marketing system).

Name Description Default
StatisticsCacheExpiration The expiration time for marketing statistics. 1 day
PromotionInformationCacheExpiration Expiration time for promotion information. TimeSpan object. 10 minutes
LinkableTypesEnabled Indicates whether Marketing Links in link selector dialog should be shown or not. false
EvaluablePromotionCacheExpiration Expiration time for evaluable promotion. 30 seconds
DiscountedEntryCacheExpiration Expiration time for discounted entries. 1 minute


Contains settings for promotions.

Name Description Default
PromotionExclusionLevel Indicates whether exclusion should be at the order or unit level. Default is Order. ExclusionLevel.Order
ApplyPromotionUnitIndividually Define whether to apply promotions units individually instead of as a group. false


Contains settings for URI conflicts.

Name Description Default
EmailRecipients Recipents string list that will get an email if any URI conflicts are found. Empty List<string>


Contains general settings for reports.

Name Description Default
OrderPerPromotionReportDataTimeout Timeout in seconds for query for order per promotion report. 30
EnableEventDrivenOrderReporting Enable event driven order reporting. false
ReportForInactivePromotionItems Add report for inactive promotion items. false


Contains settings for reporting time ranges.

Name Description Default
TimeRangesInDays Date ranges used to generate reports, for example 30, 90, or 180 days. 90
SubscriptionTimeRangesInDays Date ranges used to generate subscription reports, for example 30, 90, or 180 days. 90


Contains settings for the catalog feed.

Name Description Default
EnableEventDrivenCatalogFeed Enables event driven incremental catalog feed. false
CatalogFeedBatchSize Batch size when processing catalog feed. 50
CalculateDiscountPrices Calculate discounted prices for the feed. true
MaxEntryProcessForIncrementalCatalogFeed Max entries to process in incremental feed. 10000


Corresponds to the Mediachase.Search.SearchOptions class, containing settings for indexing and search features, see Search

The default installation of Optimizely Commerce contains the search provider LuceneSearchProvider, but this is not configured. You can use this, or create your own search provider. See below how to configure the LuceneSearchProvider in appsettings.json to configure .

"Commerce": {
    "SearchOptions": {
        "DefaultSearchProvider": "LuceneSearchProvider",
        "MaxHitsForSearchResults": 1000,
        "IndexerBasePath": "[appDataPath]\\Quicksilver\\SearchIndex",
        "IndexerConnectionString": "",
        "SearchProviders": [{
                "Name": "LuceneSearchProvider",
                "Type": "Mediachase.Search.Providers.Lucene.LuceneSearchProvider, Mediachase.Search.LuceneSearchProvider",
                "Parameters": {
                    "queryBuilderType": "Mediachase.Search.Providers.Lucene.LuceneSearchQueryBuilder, Mediachase.Search.LuceneSearchProvider",
                    "storage": "[appDataPath]\\Quicksilver\\SearchIndex",
                    "simulateFaceting": "true"
        "Indexers": [{
                "Name": "catalog",
                "Type": "EPiServer.Reference.Commerce.Site.Infrastructure.Indexing.CatalogIndexer, EPiServer.Reference.Commerce.Site"
Name Description Default
DefaultSearchProvider Gets or sets the default provider. N/A
SearchProviders Gets or sets the search providers. N/A
MaxHitsForSearchResults Gets or sets the max hits for search result. N/A
IndexerBasePath Gets or sets the base path. The path where properties of the last index will be stored. Each application will have its own folder created. N/A
IndexerConnectionString Gets or sets the connection string where build information will be stored. N/A
Indexers Gets or sets the indexers. N/A

Related topics

Do you find this information helpful? Please log in to provide feedback.

Last updated: Sep 28, 2021

Recommended reading