Custom Settings vs Custom Metadata vs Custom Labels in Salesforce

Custom Settings vs. Custom Metadata vs. Custom Labels in Salesforce: Know the Difference!

If you are a Salesforce Developer, you’ve surely worked with Custom Settings, Custom Metadata, and Custom Labels. Although all of them store data, each has a different purpose and behavior. In this article, we’ll explain their differences with practical examples so you can choose the best option in each case.

1. What are they, and when to use them?

Feature	Custom Settings	Custom Metadata	Custom Labels
Purpose	Store org-level configurations	Store deployable configurations	Store user-facing text
SOQL Query	❌ Not required	✅ Required	❌ Not required
Field Types	Limited (Text, Checkbox, Number)	More flexible	Text only
Deployable?	❌ No (records are not included in deployments)	✅ Yes (records are included)	✅ Yes
Use Cases	Simple and global values	Configurations requiring deployment	Multilingual support, UI texts
Compatible with validation rules and page layouts?	❌ No	✅ Yes	❌ No

Now, let’s see when and how to use them with examples.

2. Custom Settings: Org-level configurations

What are they?

Custom Settings store global configurations without the need for SOQL queries. There are two types:

• Hierarchical: Values change based on the profile or user. (e.g., different discounts by role).
• List: Static data applicable throughout the org (e.g., API keys, tax rates).

When to use them?

• To store fixed values like tax rates or API keys.
• To avoid SOQL limits, as Custom Settings do not require queries.
• To quickly access values in Apex without affecting performance.

Practical Example

Your company has different maximum discount percentages based on the user’s role. You can use Hierarchical Custom Settings:

• Create a Custom Setting called Discount_Settings__c with a Max_Discount__c field.
• Add values according to the profile (e.g., 30% for Salespeople, 50% for Managers).
• Access in Apex like this:
• Decimal maxDiscount = Discount_Settings__c.getInstance(UserInfo.getProfileId()).Max_Discount__c;
• This way, you avoid SOQL and keep the logic flexible.

3. Custom Metadata: Deployable Configurations

What is it?

Custom Metadata is similar to Custom Settings, but records are deployable via packages or change sets. They also allow Validation Rules and Flows.

When to use them?

• When you need to move data between environments (Development → UAT → Production).
• When values need to be queried with SOQL.
• When you want to use them in Validation Rules or Formula Fields.

Practical Example

Imagine you integrate Salesforce with multiple external services, and each has a different API key depending on the environment. Instead of hardcoding it, you can:

• Create a Custom Metadata Type called Integration_Settings__mdt with API_Key__c and Environment__c fields.
• Add records like:
• Production → API Key: PROD-12345
• Sandbox → API Key: SANDBOX-98765
• Dynamically retrieve the API key in Apex:
• Integration_Settings__mdt setting = [SELECT API_Key__c FROM Integration_Settings__mdt WHERE Environment__c = ‘Produccion’ LIMIT 1];
• String apiKey = setting.API_Key__c;
• Since the records are deployed with the code, you don’t need to configure them manually in each environment.

4. Custom Labels: Texts for Interface and Multilingual Support

What are they?

Custom Labels store static texts for the UI and allow for translations, which makes them ideal for multilingual applications.

When to use them?

• To store error messages, UI texts, or instructions.
• To support multiple languages in the application.
• To allow administrators to update messages without modifying code.

Practical Example

Let’s suppose you want to display an error message, “Invalid phone number,” in several languages. Instead of hardcoding it, you can:

• Create a Custom Label called Invalid_Phone_Message with the value “Número de teléfono inválido” (by default).
• Add translations:
• English: “Invalid phone number”
• French: “Numéro de téléphone invalide”
• Use it in Apex:
• String errorMessage = System.Label.Invalid_Phone_Message;
• Now, the message automatically changes according to the user’s language.

5. Which One Should You Use?

• Use Custom Settings → For global and static data without SOQL queries.
• Use Custom Metadata → For deployable configurations that need to be moved between environments.
• Use Custom Labels → For UI texts or messages in various languages.

Quick Decision Guide

Question	Best Option
Do I need to store global values without querying the database?	Custom Settings
Do I need to move data between environments?	Custom Metadata
Do I need multilingual support?	Custom Labels
Do I need to use it in a Validation Rule?	Custom Metadata

Conclusion

Knowing the difference between Custom Settings, Custom Metadata, and Custom Labels will help you optimize performance and scalability in Salesforce. Choosing the right tool will make your development more efficient and easier to maintain.

---