BillingSettings Metadata Type in SFDX

Architectural Overview#

The BillingSettings metadata type represents org-wide configuration toggles for Salesforce Revenue Cloud Billing (Core Billing). As enterprises transition from managed-package CPQ & Billing to core Revenue Cloud objects (BillingSchedule, BillingScheduleGroup, Invoice, InvoiceLine, CreditMemo, and Payment), Billing.settings-meta.xml governs whether core billing services, tax calculation integrations, and automated invoice posting engines are active in the org.

Directory Location and File Suffix#

Key Metadata Fields#

Declarative XML and Package Manifest Examples#

Below is the declarative Billing.settings-meta.xml configuration file and its package.xml manifest:

<?xml version="1.0" encoding="UTF-8"?>
<BillingSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableBilling>true</enableBilling>
</BillingSettings>

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

SFDX CLI Retrieval and Scratch Org Setup#

Retrieve and deploy BillingSettings using the Salesforce CLI:

# Retrieve BillingSettings from your Revenue Cloud org
sf project retrieve start --metadata Settings:Billing --target-org revcloud-org

# Deploy BillingSettings to a target sandbox or production org
sf project deploy start --metadata Settings:Billing --target-org revcloud-prod

In scratch org definitions (config/project-scratch-def.json), include BillingSettings alongside the Revenue Cloud feature flags:

{
  "orgName": "Revenue Cloud Billing Scratch Org",
  "edition": "Developer",
  "features": ["EnableSetPasswordInApi"],
  "settings": {
    "billingSettings": {
      "enableBilling": true
    }
  }
}

Senior Architect Best Practices and Gotchas#

1. Sequence Before Custom Fields on Billing Objects: In CI/CD pipelines, always deploy Settings:Billing (Billing.settings-meta.xml) before deploying custom fields, validation rules, or flows that reference standard Revenue Cloud Billing objects (Invoice, InvoiceLine, BillingSchedule). Otherwise, the custom fields will fail with Invalid object name: Invoice.
2. Cannot Be Disabled Once Invoices Exist: After enableBilling is turned on and billing schedules or invoices are generated in a sandbox or production org, attempting to deploy <enableBilling>false</enableBilling> will fail validation.

Frequently asked questions

Where is the BillingSettings metadata file stored in SFDX?

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

What license is required to deploy BillingSettings?

Your target org must have Revenue Cloud Billing or Subscription Management Billing licenses provisioned before BillingSettings flags can be enabled.

How do I retrieve BillingSettings from a sandbox?

Run sf project retrieve start --metadata Settings:Billing --target-org my-sandbox to pull Billing.settings-meta.xml into your project.