AddressSettings Metadata Type in SFDX

Architectural Overview#

Dirty address data breaks territory management, tax calculation engines, and ERP order syncs. The AddressSettings metadata type (Address.settings-meta.xml) lets architects declaratively enforce State and Country/Territory Picklists across all standard address compound fields (BillingAddress, ShippingAddress, MailingAddress) and Custom Address Fields.

By managing AddressSettings in Git, you guarantee that every scratch org, developer sandbox, and production environment shares the exact same ISO-3166 country codes, state picklist dependencies, and integrationValue mappings.

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample Address.settings-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AddressSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <countriesAndStates>
        <countries>
            <active>true</active>
            <integrationValue>United States</integrationValue>
            <isoCode>US</isoCode>
            <label>United States</label>
            <orgDefault>true</orgDefault>
            <standard>true</standard>
            <states>
                <active>true</active>
                <integrationValue>California</integrationValue>
                <isoCode>CA</isoCode>
                <label>California</label>
                <standard>true</standard>
                <visible>true</visible>
            </states>
            <states>
                <active>true</active>
                <integrationValue>New York</integrationValue>
                <isoCode>NY</isoCode>
                <label>New York</label>
                <standard>true</standard>
                <visible>true</visible>
            </states>
            <visible>true</visible>
        </countries>
    </countriesAndStates>
</AddressSettings>

Sample package.xml Manifest#

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

SFDX CLI Retrieval & Deployment#

Use the Settings:Address specifier with the Salesforce CLI to retrieve or deploy address picklist configurations:

# Retrieve the org's complete Country and State picklist configuration
sf project retrieve start --metadata "Settings:Address"

# Deploy updated Country/State ISO codes and visibility rules
sf project deploy start --source-dir force-app/main/default/settings/Address.settings-meta.xml

Senior Architect Best Practices & Gotchas#

• Integration Value Alignment: External integrations (MuleSoft, ERP connectors, Marketing Cloud) often send full country names (United States) or ISO codes (US). Align integrationValue across all integrated systems before activating State and Country Picklists, or inbound DML operations will fail with FIELD_INTEGRITY_EXCEPTION.
• Large XML File Size: Retrieving Settings:Address pulls all 240+ standard countries and thousands of states. Never hand-edit the entire file from scratch; retrieve it from a clean org, adjust visible and active flags programmatically, and commit the full file so state definitions aren’t inadvertently omitted.
• Custom Address Fields (Address Data Type): If your CustomField definitions use the compound Address field type, State and Country Picklists must be enabled first in the target org.

Frequently asked questions

What does the AddressSettings metadata type control in Salesforce?

It controls org-wide State and Country/Territory picklists, including ISO codes, integration values, active states, and visibility flags for standard address fields.

Where is AddressSettings stored in a Salesforce DX project?

It is stored at force-app/main/default/settings/Address.settings-meta.xml and referenced in package.xml under the Settings metadata type with member Address.

Can I delete a country or state using AddressSettings metadata deployment?

No, standard countries and states cannot be deleted via Metadata API. Instead, set the active and visible boolean properties to false in Address.settings-meta.xml.

Why does deploying AddressSettings take longer in large enterprise orgs?

Enabling State and Country picklists or changing integration values validates against existing address data and picklist indexes across Account, Contact, Lead, and Order records.