CurrencySettings Metadata Type in SFDX

Architectural Overview#

Enabling Multi-Currency and Advanced Currency Management (ACM) is one of the highest-impact architectural decisions in Salesforce. The moment <enableMultiCurrency>true</enableMultiCurrency> is deployed via CurrencySettings (Currency.settings-meta.xml), Salesforce permanently alters the database schema of the entire org:

• Every standard and custom object automatically receives a CurrencyIsoCode picklist field.
• Standard CurrencyType and DatedConversionRate objects are provisioned.
• All Currency fields display both the record’s transaction currency and the user’s personal converted currency in parentheses (when enableParentheticalCurrencyConversion is enabled).

By managing Currency.settings-meta.xml in SFDX, architects guarantee that scratch orgs, developer sandboxes, and integration environments mirror Production’s multi-currency state so SOQL queries referencing CurrencyIsoCode or convertCurrency(Amount) compile and pass tests reliably.

SFDX Directory and File Suffix#

Key Metadata Fields#

CurrencySettings exposes boolean flags that control Multi-Currency, Advanced Currency Management, and visual currency formatting.

Declarative XML Example#

Below is a standard global enterprise Currency.settings-meta.xml enabling Multi-Currency, Advanced Currency Management (dated exchange rates), and parenthetical currency conversion.

<?xml version="1.0" encoding="UTF-8"?>
<CurrencySettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableCurrencyEffectiveDates>true</enableCurrencyEffectiveDates>
    <enableCurrencySymbolWithIso>false</enableCurrencySymbolWithIso>
    <enableMultiCurrency>true</enableMultiCurrency>
    <enableParentheticalCurrencyConversion>true</enableParentheticalCurrencyConversion>
    <isParallelExecEnabled>true</isParallelExecEnabled>
</CurrencySettings>

package.xml Manifest#

Reference CurrencySettings via the Settings metadata type with member Currency:

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

Querying Active Currencies and Dated Rates via SOQL#

Once CurrencySettings enables Multi-Currency and ACM, use standard SOQL to inspect active currencies (CurrencyType), dated exchange rates (DatedConversionRate), and converted amounts (convertCurrency()).

1. Query Active Org Currencies and Corporate Currency (CurrencyType)#

SELECT Id, IsoCode, ConversionRate, DecimalPlaces, IsActive, IsCorporate
FROM CurrencyType
WHERE IsActive = true
ORDER BY IsCorporate DESC, IsoCode ASC

2. Query Dated Exchange Rates (DatedConversionRate)#

SELECT Id, IsoCode, ConversionRate, StartDate, NextStartDate
FROM DatedConversionRate
WHERE StartDate <= TODAY AND NextStartDate > TODAY
ORDER BY IsoCode ASC

3. SFDX CLI Retrieve and Deploy Commands#

# Retrieve CurrencySettings from the org
sf project retrieve start --metadata Settings:Currency

# Deploy CurrencySettings to a scratch org or sandbox
sf project deploy start --metadata Settings:Currency

Architect Best Practices and Gotchas#

• Irreversible Multi-Currency Activation: Never deploy <enableMultiCurrency>true</enableMultiCurrency> to Production without full UAT sign-off. Once enabled, enableMultiCurrency cannot be reverted to false even by Salesforce Support.
• ISV Managed Package Compatibility: If you are building a Managed Package (1GP or 2GP), avoid hardcoding CurrencyIsoCode in static SOQL queries unless Multi-Currency is a mandatory package dependency. Use Dynamic SOQL and Schema.getGlobalDescribe() / UserInfo.isMultiCurrencyOrganization() so your package works in both single-currency and multi-currency subscriber orgs.

Frequently asked questions

Can Multi-Currency be disabled via CurrencySettings once enabled?

No. Enabling Multi-Currency (enableMultiCurrency) is a permanent, irreversible architectural change in a Salesforce org that adds CurrencyIsoCode fields to every standard and custom object.

Where is CurrencySettings stored in an SFDX project?

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

What is the difference between enableMultiCurrency and enableCurrencyEffectiveDates?

enableMultiCurrency activates multiple currencies and the CurrencyType table, while enableCurrencyEffectiveDates activates Advanced Currency Management (Dated Exchange Rates stored in DatedConversionRate) for Opportunities.

Why did my Apex package stop compiling after enabling Multi-Currency?

Once Multi-Currency is enabled, every SOQL query that selects a Currency field alongside CurrencyIsoCode or dynamic currency references behaves differently, and hard-coded single-currency assumptions in tests or rollups must account for CurrencyIsoCode.