Architectural Overview

Salesforce B2B Commerce and D2C Commerce built natively on the core Lightning platform rely on CommerceSettings (Commerce.settings-meta.xml) as their foundational activation switch. Enabling commerceEnabled provisions the core Commerce data model—including WebStore, WebCart, CartDeliveryGroup, BuyerGroup, PriceAdjustmentSchedule, and ProductAttributeSet—and integrates Commerce workspaces into Experience Cloud (Network and ExperienceBundle).

In CI/CD pipelines, CommerceSettings must be deployed in the earliest pre-deployment phase (or baked into the scratch org definition) because any CustomObject customizations, Apex cart calculators, or checkout Flow definitions referencing WebCart or WebStore will fail compilation until commerceEnabled is true.

CommerceSettings (Commerce.settings-meta.xml) commerceEnabled = true Unlock Core Schema (WebStore, WebCart, BuyerAccount) commerceAppEnabled & Diagnostic Logging B2B / D2C Experience Cloud Storefronts Apex Cart Calculators & Checkout Flows

Directory Location and File Suffix

In Salesforce DX projects, CommerceSettings is stored in the settings folder as Commerce.settings-meta.xml.

Property Value
Directory Path (SFDX) force-app/main/default/settings/
File Name (SFDX) Commerce.settings-meta.xml
Classic Metadata File settings/Commerce.settings
Package.xml Type & Member <name>Settings</name> with <members>Commerce</members>

Key Metadata Fields

The following table details the key XML flags on CommerceSettings in API version 68.0 (Winter ’27):

Field Name Field Type Required Architectural Description
commerceEnabled boolean Yes Master switch that enables Salesforce B2B/D2C Commerce and unlocks Commerce standard objects. Once true, it cannot be reverted to false.
commerceAppEnabled boolean No Enables the Commerce Lightning application and workspace navigation for merchandising admins.
commerceDiscoveryExpansion boolean No Enables expanded catalog and Einstein Commerce discovery capabilities where licensed.
commerceDiagnosticEventEnabled boolean No Emits diagnostic events for cart, checkout, and pricing extensions to assist with troubleshooting storefront errors.

Declarative Metadata Example

The following Commerce.settings-meta.xml activates Commerce, the Commerce App, and diagnostic events for storefront troubleshooting:

force-app/main/default/settings/Commerce.settings-meta.xml
<?xml version="1.0" encoding="UTF-8"?>
<CommerceSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <commerceAppEnabled>true</commerceAppEnabled>
    <commerceDiagnosticEventEnabled>true</commerceDiagnosticEventEnabled>
    <commerceDiscoveryExpansion>false</commerceDiscoveryExpansion>
    <commerceEnabled>true</commerceEnabled>
</CommerceSettings>

Package Manifest (package.xml)

manifest/package.xml
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Commerce</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval and Deployment

Retrieve and deploy CommerceSettings using the Salesforce CLI (sf):

Terminal
# Retrieve CommerceSettings into force-app/main/default/settings/Commerce.settings-meta.xml
sf project retrieve start --metadata Settings:Commerce

# Deploy CommerceSettings to enable Commerce in a target org
sf project deploy start --metadata Settings:Commerce

Architect Best Practices and Gotchas

Warning

CommerceSettings depends on Experience Cloud (CommunitiesSettings / enableNetworksEnabled) and Person Accounts (for D2C Commerce) being enabled in the target org. If you deploy Settings:Commerce before Settings:Communities, the deployment will fail.

  • Two-Stage CI/CD Deployment: When initializing a brand-new sandbox or scratch org, deploy Settings:Communities and Settings:Commerce first before deploying WebCart custom fields, BuyerAccount sharing rules, or WebStore ExperienceBundle storefronts.
  • Enable Diagnostic Events in Lower Environments: Keep <commerceDiagnosticEventEnabled>true</commerceDiagnosticEventEnabled> enabled in SIT and UAT sandboxes so architects can inspect CommerceDiagnosticEvent logs when debugging custom Pricing, Inventory, or Tax extension providers.

Frequently asked questions

What does CommerceSettings control on the Salesforce platform?

CommerceSettings enables Salesforce Commerce on Core (B2B Commerce and D2C Commerce), unlocking standard Commerce objects such as WebStore, WebCart, CartItem, ProductAttribute, and BuyerAccount.

How is CommerceSettings declared in package.xml?

In package.xml, specify Settings as the type and Commerce as the member, which maps to force-app/main/default/settings/Commerce.settings-meta.xml in SFDX source format.

Why do WebCart or WebStore custom field deployments fail in new sandboxes or scratch orgs?

Standard Commerce objects like WebStore and WebCart are hidden in the schema until commerceEnabled is set to true in CommerceSettings and CommunitiesSettings is enabled.

Can commerceEnabled be set back to false once enabled in an org?

No. Once Commerce is enabled in a Salesforce org via CommerceSettings or Setup, it cannot be disabled through the Metadata API.

Comments

Questions, corrections and tips are welcome. Comments are GitHub Discussions, so you sign in with GitHub.