HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Option configuration classes

Introduces various configuration possibilities and their settings in Optimizely Customized Commerce.

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



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 Work with entity objects.

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


Contains a set of meta object-related settings.

MaxListObjectGets or sets the max list object, for example records to retrieve from meta object system while querying.1000
UseCacheGets or sets a value indicating whether cache should be used while querying.false
CacheItemExpirationGets or sets the cache item expiration in seconds.30
UseSPOptimizationGets or sets a value indicating whether [use sp optimization].false
SPItemExpirationGets or sets the SP item expiration in minutes.10080
InstancesGets or sets the business object services; list of MetaObjectInstance objects.Empty
TypesGets or sets the types; ListEmpty


Contains a set of meta data-related settings.

CacheExpirationThe default expiration time.10 minutes
DisableVersionSyncGets 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
AllowUntypedCatalogContentAllows for no models to need to exist for catalog content.false
RemoveOrphanedMetaKeysBatchSizeBatch 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"
AutoConfigureDetermines whether to auto configure the Catalog system when first initialized.true
CacheContains options for the catalog cache system. Instance of CatalogCacheOptions.See CatalogCacheOptions
SalePriceTypesRepresents configures SalePriceTypes; ListEmpty
ShowVariationListPriceEnables the display of the obsolete variation list price in the catalog entry edit user interfacefalse
CatalogImportBatchSizeGets or sets the batch size of the entries when importing a catalog.200
CommandTimeoutGets or sets a value indicating whether to user custom sql command timeout or not in seconds.-1
CatalogEventLevelUsed to control which events will be raised remotely.CatalogEventLevel.All
DisableCatalogEventDrivenIndexingDisables event indexing for the Customized Commerce search provider not Search & Navigation (Find).false
SkipCatalogContentModelCheckDisables validating models exist in the application domain.false
IgnorePropertyAndMetafieldMisMatchIgnores Meta field mismatches in catalog content scanning.false
SimplifiedCatalogListingThresholdNumber of records in which the catalog listing view does not group products and variants.2000
DraftMigrationBatchSizeBatch size when migrating legacy drafts to the new version store.5000
DraftMigrationTimeSpanTimeout for draft store migration from legacy to new version store in hours.1


Contains settings for the Catalog subsystem caching.

UseCacheIndicates if the cache is enabled.true
ContentVersionCacheExpirationExpiration time for catalog content versions.10
CollectionCacheExpirationExpiration time for catalog relations, catalog associations, catalog nodes, catalog entries, catalog, tax categories and merchants.15
EntryCacheExpirationExpiration time for entries.15
NodeCacheExpirationExpiration time for nodes.15
CurrencyCacheExpirationExpiration time for currencies.1 hour
IdentityResolverCacheExpirationExpiration time for the identity resolver.10
InventoryCacheExpirationExpiration time for inventory.5
PriceCacheExpirationExpiration time for price.10
PriceDetailsCacheExpirationExpiration time for price details.10


Contains settings for URI validation, see Routing.

UseLessStrictEntryUriSegmentValidationGets 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 Serializable carts.

        "Commerce": {
            "ApplicationOptions": {
                "Features": {
                    "SerializedCarts": {
                        "Feature": "SerializedCarts",
                        "State": 1, // 0 is enabled, 1 for disabled
                        "Type": "Mediachase.Commerce.Core.Features.SerializedCarts, Mediachase.Commerce"
DefaultApplicationNameDefines default value used for the application name."ECApplication"
CacheCache settings for the application.See ApplicationCacheOptions
AutoMigrateAuto-migrate Customized Commerce.true
RolesApplication roles. Key/value dictionary.EPiServer-specified default roles.
FeaturesConfigurable application features; SerializedCarts (enabled), WorkflowsVNext(disabled).N/A


Contains settings for Application-related caching.

EnabledDetermines whether in-memory caching is enabled or not.true


Contains settings for the Customers subsystem.

AutoInstallGets a value indicating whether to automatically install metadata definitions for entities related to customers/contacts.true
DemoInstallGets a value indicating whether to install sample customers in the system automatically.true
CacheConfig settings that define where caching is enabled and timeouts related to it.See CustomerCacheOptions


Contains settings for the Customers subsystem caching.

UseCacheGets or sets if the cache is enabled.true
ContactCollectionCacheExpirationGets or sets the contact collection expiration time.1 minute
ContactCacheExpirationGets or sets the contact expiration time.1 minute
AddressCollectionCacheExpirationGets or sets the address collection expiration time.1 minute
AddressCacheExpirationGets or sets the address expiration time.1 minute
CreditCardCollectionCacheExpirationGets or sets the credit card collection expiration time.1 minute
OrganizationCollectionCacheExpirationGets or sets the organization collection expiration time in minutes.1 minute
OrganizationCacheExpirationGets or sets the organization expiration time.1 minute


Contains settings for data index management.

DisableRetryPolicyDisabled the retry policy for the sql data provider.false
LowFragmentationThresholdUsed by the maintain database indexes job.10
HighFragmentationThresholdUsed by the maintain database indexes job.30
DataBaseIndicesJobCommandTimeOutUsed by the maintain database indexes job.-1 for default timeout (30 seconds)


Contains settings for the Markets subsystem.

CacheExpirationThe default expiration time used in MarketService.5 minutes


Contains settings for the Orders subsystem.

NewOrderStatusGets the new order status.InProgress
AutoConfigureGets a value indicating whether to auto-configure the Order system when first initialized.true
ShipmentAutoReleaseTimeoutGets or sets the shipment auto-release timeout.1 day
DisableOrderDataLocalizationFlag to indicate if order data localization is disabled.false
MetaClassesContains the names of meta classes for orders that are stored in the configuration file.EPiServer-defined meta classes.
MappedTypesGets the mapping of order-related entities to actual implementation classes.EPiServer-defined mapped types.
CacheThe cache options for Orders.See OrderCacheOptions


Contains settings for the Order subsystem caching.

UseCacheIndicates if the cache is enabled.true
IsOrderRepositoryCacheDisabledIndicates if the order repository cache is disabled.false
JurisdictionCacheExpirationExpiration time for jurisdictions.1 hour
TaxCacheExpirationExpiration time for taxes.1 hour
CountryCacheExpirationExpiration time for countries.1 hour
PaymentCacheExpirationExpiration time for payments.1 day
ShippingCacheExpirationExpiration time for shipping.1 day
StatusCacheExpirationExpiration time for status.10 seconds
PickListCacheExpirationExpiration time for pick lists.20 seconds
OrderCacheExpirationLegacyExpiration time for legacy ordergroups.10 minutes
OrderCacheExpirationExpiration time for ordergroups.10 minutes
UserOrderCacheExpirationExpiration time for user order.5 minutes


Contains settings for the legacy _Marketing_subsystem (replaced by the Marketing and campaigns system).

StatisticsCacheExpirationThe expiration time for marketing statistics.1 day
PromotionInformationCacheExpirationExpiration time for promotion information. TimeSpan object.10 minutes
LinkableTypesEnabledIndicates whether Marketing Links in link selector dialog should be shown or not.false
EvaluablePromotionCacheExpirationExpiration time for evaluable promotion.30 seconds
DiscountedEntryCacheExpirationExpiration time for discounted entries.1 minute


Contains settings for Promotions.

PromotionExclusionLevelIndicates whether exclusion should be at the order or unit level. Default is Order.ExclusionLevel.Order
ApplyPromotionUnitIndividuallyDefine whether to apply promotions units individually instead of as a group.false


Contains settings for URI conflicts.

EmailRecipientsRecipents string list that will get an email if any URI conflicts are found.Empty List


Contains general settings for Reports.

OrderPerPromotionReportDataTimeoutTimeout in seconds for query for order per promotion report.30
EnableEventDrivenOrderReportingEnable event driven order reporting.false
ReportForInactivePromotionItemsAdd report for inactive promotion items.false


Contains settings for reporting time ranges.

TimeRangesInDaysDate ranges used to generate reports, for example 30, 90, or 180 days.90
SubscriptionTimeRangesInDaysDate ranges used to generate subscription reports, for example 30, 90, or 180 days.90


Contains settings for the catalog feed.

EnableEventDrivenCatalogFeedEnables event driven incremental catalog feed.false
CatalogFeedBatchSizeBatch size when processing catalog feed.50
CalculateDiscountPricesCalculate discounted prices for the feed.true
MaxEntryProcessForIncrementalCatalogFeedMax 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 Customized Commerce installation contains the search provider LuceneSearchProvider, but this is not configured. You can use this, or create your 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"
DefaultSearchProviderGets or sets the default provider.N/A
SearchProvidersGets or sets the search providers.N/A
MaxHitsForSearchResultsGets or sets the max hits for search result.N/A
IndexerBasePathGets 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
IndexerConnectionStringGets or sets the connection string where build information will be stored.N/A
IndexersGets or sets the indexers.N/A