ProductSettings Metadata Type in SFDX

Architectural Overview#

In Salesforce Sales Cloud, products and price books form the transactional backbone for opportunities, quotes, and orders. Enterprise organizations with recurring revenue or subscription billing models frequently leverage Product Schedules to track multi-period revenue recognition and phased product deliveries.

The ProductSettings metadata type is a foundational org configuration file. It provisions standard scheduling objects—specifically OpportunityLineItemSchedule—and governs whether users can establish revenue schedules, quantity schedules, or default standard price book associations.

In automated enterprise CI/CD pipelines, deploying ProductSettings prior to schema, Apex, or Flow deployments is essential to avoid build failures caused by missing scheduling sObjects.

Directory and File Conventions#

In SFDX source format, ProductSettings is stored in the settings/ directory and referenced as Settings:Product:

Key Metadata Fields#

The XML schema of ProductSettings exposes several critical commercial flags:

Declarative XML and Package Manifest Examples#

Below is a production Product.settings-meta.xml file configured for recurring revenue business models:

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

Scratch Org Definition Configuration#

{
  "orgName": "SaaS Billing Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "productSettings": {
      "enableRevenueSchedule": true,
      "enableQuantitySchedule": true,
      "enableCascadeDeletePriceBookEntries": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage ProductSettings using Salesforce CLI commands:

# Retrieve ProductSettings from the target org
sf project retrieve start --metadata Settings:Product

# Deploy ProductSettings to the target org
sf project deploy start --metadata Settings:Product

# Validate settings deployment without committing changes
sf project deploy validate --metadata Settings:Product

Architect Best Practices and Gotchas#

• CI/CD Pipeline Sequencing: If any ApexClass or Flow references OpportunityLineItemSchedule, ProductSettings must be deployed before compiling code; otherwise, deployments fail with sObject type does not exist.
• Irreversible Deactivation Constraints: Salesforce blocks disabling enableRevenueSchedule if active OpportunityLineItemSchedule records exist in the database.
• Reporting and Forecasting Impact: Changing scheduling settings directly alters how collaborative forecasting engines aggregate pipeline revenue across fiscal periods.

Frequently asked questions

What core product features are controlled by ProductSettings?

It controls Revenue and Quantity schedules, standard price book defaults, and price book entry cascade deletion rules.

Where is ProductSettings located in an SFDX source project?

It resides at force-app/main/default/settings/Product.settings-meta.xml and is retrieved using Settings:Product.

Why did my Apex deployment referencing OpportunityLineItemSchedule fail?

The OpportunityLineItemSchedule object does not exist until enableRevenueSchedule or enableQuantitySchedule is set to true in ProductSettings.

Can ProductSettings be deployed into scratch orgs?

Yes, by adding productSettings under the settings block in project-scratch-def.json.