Commerce Engine policies

Current version: 9.3

You use policies to define Commerce Engine configuration. A policy is a group of settings that control the behavior of a specific piece of functionality within the Commerce Engine.

Each Commerce plugin contributes a set of policies that define behavior for the functionality provided by the plugin. For example, the Search plugin provides policies that govern the type of entity to be added to the Search index (the SearchScope policy), and which View fields to index for a particular entity (the Indexable policy). The Commerce Core plugin provides an EntityCaching policy that determines the caching behavior for commerce entities.

For a list of Commerce Engine policies and the parameters available in each policy, see the List of Commerce Engine policies section at the end of this topic.

The following is an example of an Entity Caching policy:

  "$type": "Sitecore.Commerce.Core.EntityCachingPolicy, Sitecore.Commerce.Core", 
  "EntityFullName": "Sitecore.Commerce.Plugin.Content.ContentPath", 
  "AllowCaching": true, 
  "Priority": "Normal", 
  "Expiration": 86400000, 
  "HasNegativeCaching": true, 
  "CacheName": "ContentPaths", 
  "EntityIdPrefix": "Entity-ContentPath" 

Every policy has a default configuration, and unless explicitly configured otherwise, the Commerce Engine uses the policy's default settings to determine behavior for the functionality it defines.

You can configure policy behavior explicitly by including the policy in a policy set file (for global configuration in more than one environment), or by including the policy in an individual environment configuration (JSON) file. When you specify a policy in an environment configuration file, that local configuration overrides the default policy behavior.

An overview of how policies in plugin are exposed for configuration in policy sets and environment configuration files.

Policy sets

A policy set is a file that contains a collection of policies, with a specific configuration. You use policy sets to group policies that you want to use in more than one environment, so that you do not need to repeat the same policy configuration in each environment JSON file.

The Sitecore XC solution includes the following default policy set files in the Commerce Engine SDK.*.zip package, in the wwwroot\data\Environments folder:

  • Core.ControllerMethodRoles.PolicySet-1.0.0.json

  • Plugin.AccessByRoles.PolicySet-1.0.0.json

  • Plugin.Caching.PolicySet-1.0.0.json

  • Plugin.Catalog.PolicySet-1.0.0.json

  • Plugin.CatalogIndexing.PolicySet-1.0.0.json

  • Plugin.Content.PolicySet-1.0.0.json

  • Plugin.LocalizeEntities.PolicySet-1.0.0.json

  • Plugin.Minions.PolicySet-1.0.0.json

  • Plugin.Payments.Braintree.PolicySet-1.0.0.json

  • Plugin.Plugin.PolicySet-1.0.0.json

  • Plugin.Relationships.PolicySet-1.0.0.json

  • Plugin.Search.Azure.PolicySet-1.0.0.json (for the Azure search provider)

  • Plugin.Search.PolicySet-1.0.0.json

  • Plugin.Search.Solr.PolicySet-1.0.0.json (for the Solr search provider)

  • Plugin.SQL.PolicySet-1.0.0.json

  • Plugin.SQL.Sharding.PolicySet-1.0.0.json

  • Plugin.Validation.PolicySet-1.0.0.json

  • Plugin.Versioning.PolicySet-1.0.0.json

  • Plugin.ViewTemplateComposer.PolicySet-1.0.0.json

  • Plugin.Workflow.PolicySet-1.0.0.json

To ensure that a Commerce environment inherits the behavior defined in a particular policy set, you must include a reference to that policy set in the environment's JSON file.

For example, to apply caching behavior specified in the global Caching policy set to a specific environment, you add an entry for that policy set in the Policies collection of the environment JSON file (for example, Plugin.Habitat.CommerceShops.1.0.0.json), as follows:

     "$type": "Sitecore.Commerce.Core.PolicySetPolicy, Sitecore.Commerce.Core",
        "PolicySetId": "Entity-PolicySet-CachingPolicySet"

If you change the policy configuration in any policy set file, the behavior changes for any environment that references the policy set file.

Local policy configuration

You define policy configuration for a single environment, by adding a policy to the environment's configuration (JSON) file.

For example, the Carts plugin includes policies that govern cart behavior. One policy, the CalculateCart policy, determines whether (and when) the Commerce Engine recalculates a cart total. Promotions, line prices, shipping costs, or other cart operations affect the cart total. For optimized performance, particularly in a Shops environment, the AlwaysCalculate parameter is set to false by default.

However, in an Authoring environment, you might want to enable the AlwaysCalculate parameter so that a business user can test a new promotion, for example, and ensure that any discounts are applied to the cart total correctly, in real time.

To enable the parameter for the Authoring environment only, you would add an instance of the Calculate Cart policy to the Policies collection in the environment JSON file (for example, Plugin.Habitat.CommerceAuthoring.json) and set the AlwaysCalculate parameter to true as follows:

    "$type": "Sitecore.Commerce.Plugin.Carts.CalculateCartPolicy, Sitecore.Commerce.Plugin.Carts",
        "AlwaysCalculate": true

Because the Calculate Cart policy is explicitly included in the environment JSON file, the Commerce Engine uses the setting in the file to override the default behavior of the Calculate Cart policy, for that specific environment.


If you make any changes to an environment JSON file, you must bootstrap the Commerce Engine to propagate the changes to the Global database.

List of Commerce Engine policies

Policies for the different Commerce Engine services are defined in the plugins that provide those micro-services. The following table summarizes all of the policies available by micro-service. Click the link in the policies column to go to a more detailed topic on those specific policies.

Commerce plugin



Core policies


Views policies


Orders policies

Delayed Availability policies


Returns policies


Cart policies


Customer policies


Pricing policies


Promotions policies


Coupons policies


Entitlements policies


Catalog and Relationship policies


Availability policies




Inventory policies


Payment policies


Fulfillment policies


Search policies

Do you have some feedback for us?

If you have suggestions for improving this article,