AccountSettings Metadata Type in SFDX

Architectural Overview#

The AccountSettings metadata type is one of the most consequential configuration files in any Salesforce DX repository. It controls the availability of major relational tables in the core CRM schema—most notably AccountTeamMember (Account Teams), AccountContactRelation (Contacts to Multiple Accounts), and AccountRelationship (Account Relationships).

In enterprise CI/CD and scratch org automation, failing to deploy AccountSettings before compiling schema and code is a leading cause of broken builds. Whenever an ApexClass, Flow, or layout references AccountTeamMember or AccountContactRelation, Account.settings-meta.xml must be deployed first to provision those objects.

Directory and File Conventions#

In SFDX source format (apiVersion 68.0), AccountSettings is stored in the settings/ directory and referenced as Settings:Account.

Key Metadata Fields#

The AccountSettings XML schema exposes the following architectural flags:

Declarative XML and Package Manifest Examples#

Below is a production-hardened Account.settings-meta.xml file for an enterprise B2B org:

<?xml version="1.0" encoding="UTF-8"?>
<AccountSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableAccountHistoryTracking>true</enableAccountHistoryTracking>
    <enableAccountOwnerReport>false</enableAccountOwnerReport>
    <enableAccountRelationships>true</enableAccountRelationships>
    <enableAccountTeams>true</enableAccountTeams>
    <showViewHierarchyLink>true</showViewHierarchyLink>
</AccountSettings>

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

{
  "orgName": "Enterprise B2B Sales Scratch Org",
  "edition": "Enterprise",
  "features": ["ContactsToMultipleAccounts"],
  "settings": {
    "accountSettings": {
      "enableAccountTeams": true,
      "enableAccountRelationships": true,
      "enableAccountHistoryTracking": true,
      "showViewHierarchyLink": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage AccountSettings using the Salesforce CLI (sf):

# Retrieve Account.settings-meta.xml from the org
sf project retrieve start --metadata Settings:Account

# Deploy Account.settings-meta.xml to the target org
sf project deploy start --metadata Settings:Account

Architect Best Practices and Gotchas#

• Security Exposure with enableAccountOwnerReport: Keep enableAccountOwnerReport set to false when your Account OWD (sharingModel on CustomObject) is Private and customer existence is confidential. Setting it to true lets any user see basic Account names and owners across the org via standard reporting.
• Irreversible Deletion Constraints: You cannot set enableAccountTeams to false if any ApexClass, trigger, or validation rule in the org references AccountTeamMember.

Frequently asked questions

What core Salesforce features are enabled by AccountSettings?

AccountSettings enables Account Teams, Contacts to Multiple Accounts (AccountContactRelation), Account Relationships, Account Owner Reports, and Account Hierarchy column display.

Why did my Apex class referencing AccountTeamMember fail to compile during deployment?

The AccountTeamMember object does not exist in an org until enableAccountTeams is set to true inside AccountSettings.

How do I retrieve AccountSettings in an SFDX project?

Run sf project retrieve start with the metadata flag set to Settings:Account, which writes force-app/main/default/settings/Account.settings-meta.xml.

Can I disable Contacts to Multiple Accounts via AccountSettings if AccountContactRelation records exist?

No. Salesforce blocks disabling Contacts to Multiple Accounts while indirect AccountContactRelation records exist in the database.