CompanySettings Metadata Type in SFDX

Architectural Overview#

Every date-driven aggregate in Salesforce—Opportunity pipeline reports, Collaborative Forecasts, Quota attainment, and Einstein Analytics fiscal bucketing—depends on the organization’s fiscal calendar configuration. The CompanySettings metadata type allows architects to version-control and deploy the organization’s fiscal year rules (fiscalYear) via Company.settings-meta.xml.

In multi-org enterprise environments or scratch org CI/CD pipelines, failing to align CompanySettings before loading test data or running Apex unit tests that query THIS_FISCAL_QUARTER or THIS_FISCAL_YEAR SOQL date literals causes subtle, calendar-dependent test failures whenever the corporate fiscal year starts in a month other than January (for example, February for retail or April/July for public sector and SaaS).

SFDX Directory and File Suffix#

Key Metadata Fields#

CompanySettings contains the nested fiscalYear (FiscalYearSettings) complex type that governs standard fiscal calendar calculations.

Declarative XML Example#

Below is a typical SaaS enterprise Company.settings-meta.xml configuring a February 1st fiscal year start where the fiscal year is named after the ending calendar year (mirroring Salesforce’s own FY calendar).

<?xml version="1.0" encoding="UTF-8"?>
<CompanySettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableCustomFiscalYear>false</enableCustomFiscalYear>
    <fiscalYear>
        <fiscalYearNameBasedOn>endingMonth</fiscalYearNameBasedOn>
        <fiscalYearStartMonth>2</fiscalYearStartMonth>
    </fiscalYear>
</CompanySettings>

package.xml Manifest#

Like all org settings metadata types, CompanySettings is referenced in package.xml using the <name>Settings</name> tag and <members>Company</members>:

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

Querying Fiscal Settings via SOQL and SFDX CLI#

You can inspect the active CompanySettings state at runtime by querying the Organization and FiscalYearSettings standard objects in SOQL, or retrieve the declarative XML using the sf CLI.

1. Query Standard Fiscal Year Configuration on Organization#

SELECT Id, Name, FiscalYearStartMonth, UsesStartDateAsFiscalYearName, DefaultLocaleSidKey, TimeZoneSidKey
FROM Organization
LIMIT 1

2. Query Custom or Standard Fiscal Periods via FiscalYearSettings#

SELECT Id, Name, StartDate, EndDate, YearType, IsStandardYear, Description
FROM FiscalYearSettings
ORDER BY StartDate DESC
LIMIT 10

3. SFDX CLI Retrieve and Deploy Commands#

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

# Deploy updated fiscal year settings to a sandbox or scratch org
sf project deploy start --metadata Settings:Company

Architect Best Practices and Gotchas#

• Include in Scratch Org Definition or Baseline Package: Always include Company.settings-meta.xml (or set companySettings in config/project-scratch-def.json) in your CI/CD baseline so scratch orgs match Production’s FiscalYearStartMonth before Apex tests execute.
• Forecast Recalculation Impact: Changing fiscalYearStartMonth in an active sandbox or production org triggers an immediate recalculation of all Opportunity fiscal period stamps (Fiscal, FiscalQuarter, FiscalYear fields on Opportunity) and invalidates existing Collaborative Forecast quotas for misaligned periods.

Frequently asked questions

What org-wide preferences are controlled by CompanySettings?

CompanySettings manages the organization's standard fiscal year start month, whether the fiscal year name is based on the starting or ending month, and whether dated exchange rates (enableCustomFiscalYear) are active.

Where is CompanySettings stored in an SFDX project?

It is stored at force-app/main/default/settings/Company.settings-meta.xml and referenced in package.xml as Settings with member Company.

Can you disable Custom Fiscal Years via CompanySettings once enabled?

No. Enabling custom fiscal years in Salesforce is an irreversible one-way change in an org because opportunities, forecasts, and reports immediately restructure around custom period tables.

How do I query current fiscal year settings using SOQL?

Query the Organization standard object for FiscalYearStartMonth and UsesStartDateAsFiscalYearName, or query FiscalYearSettings and Period objects for custom fiscal calendars.