OpportunitySettings Metadata Type in SFDX

Architectural Overview#

OpportunitySettings is an org-level settings metadata type that governs the core business capabilities of the Salesforce Sales Cloud Opportunity pipeline. It provisions and configures critical revenue management mechanisms, including Opportunity Teams (OpportunityTeamMember), Opportunity Splits, product addition prompts on deal creation, and customizable rollup calculations.

From an Enterprise Architect perspective, OpportunitySettings acts as a structural gatekeeper. Just like AccountSettings, attempting to compile Apex classes, sharing rules, or permission sets that reference team selling constructs before OpportunitySettings has activated them in the target org results in compile-time build failures.

Directory and File Conventions#

OpportunitySettings files are located in the settings/ directory and referenced as Settings:Opportunity.

Key Metadata Fields#

The XML schema for OpportunitySettings defines core pipeline and team selling behaviors:

Declarative XML and Package Manifest Examples#

A standard production settings manifest for enterprise team selling and deal governance:

<?xml version="1.0" encoding="UTF-8"?>
<OpportunitySettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <autoActivateNewReminders>false</autoActivateNewReminders>
    <customizableRollups>false</customizableRollups>
    <enableOpportunityTeam>true</enableOpportunityTeam>
    <enableUpdateReminders>true</enableUpdateReminders>
    <promptToAddProducts>true</promptToAddProducts>
</OpportunitySettings>

Scratch Org Configuration (config/project-scratch-def.json)#

To enable Opportunity Teams and deal product prompts in scratch orgs:

{
  "orgName": "Enterprise Sales Pipeline Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "opportunitySettings": {
      "enableOpportunityTeam": true,
      "promptToAddProducts": true,
      "enableUpdateReminders": false
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage OpportunitySettings with the Salesforce CLI:

# Retrieve Opportunity settings from the org
sf project retrieve start --metadata Settings:Opportunity

# Deploy Opportunity settings to the target org
sf project deploy start --metadata Settings:Opportunity

Architect Best Practices and Gotchas#

• Build Sequence Dependencies: Any Apex code, Flow, or Permission Set referencing OpportunityTeamMember requires enableOpportunityTeam: true. Deploy Settings:Opportunity in your baseline deployment phase before application code.
• Data Deletion Risks on Disable: Disabling enableOpportunityTeam in an environment will permanently delete all existing OpportunityTeamMember records and remove associated implicit record sharing.
• Split Configuration Sequence: If your project uses Opportunity Splits (OpportunitySplitType), ensure OpportunitySettings is deployed and active before deploying split types; otherwise, metadata deployment will fail with dependency errors.

Frequently asked questions

What core standard objects are provisioned by OpportunitySettings?

Enabling Opportunity Teams provisions the OpportunityTeamMember and UserOpportunityTeamMember standard entities in the org schema.

Can Opportunity Splits be enabled directly within OpportunitySettings?

Enabling opportunity teams via OpportunitySettings is the architectural prerequisite before Opportunity Splits can be activated.

Where is OpportunitySettings stored in an SFDX project?

It is stored in force-app/main/default/settings/Opportunity.settings-meta.xml and retrieved as Settings:Opportunity.