Custom Settings
Custom Settings are a Salesforce data construct that store configuration data accessible from Apex, Flow, validation rules, and formula fields without consuming SOQL governor limits.
Definition
Custom Settings are a Salesforce data construct that store configuration data accessible from Apex, Flow, validation rules, and formula fields without consuming SOQL governor limits. They look like custom objects in Setup but live in an in-memory cache, which makes reads effectively free in code. The two types are List Custom Settings, which hold a flat list of named records, and Hierarchy Custom Settings, which support an inheritance hierarchy of org-default, profile-level, and user-level overrides for the same setting.
Custom Settings were the standard configuration mechanism for most of Salesforce's history. Tax rates, integration endpoints, feature flags, geocoding API keys, validation thresholds: all classic Custom Settings use cases. Custom Metadata Types, introduced in 2015, have replaced Custom Settings for most new use cases because metadata can be deployed through change sets and tracked in version control. But Custom Settings remain the right tool for user-specific or profile-specific overrides (which Custom Metadata cannot do natively) and for any configuration that admins need to edit in production without metadata deployments.
How Custom Settings store configuration without burning queries
List versus Hierarchy types and when to use each
List Custom Settings store a flat list of records, each with a Name field as the primary key. Use them for static configuration with multiple entries: tax rates by country, currency conversion factors, feature flag toggles. Hierarchy Custom Settings store one record per User, Profile, or Organization, and Apex retrieves the right value through the inheritance chain. Use them when different users need different values for the same setting: API rate limits per user, default page sizes per profile, sandbox versus production toggles at the org level.
The cache benefit and free reads
Custom Settings are cached in the org's application server memory, so reads through the standard Apex APIs (MyCustomSetting__c.getInstance, MyCustomSetting__c.getAll, MyCustomSetting__c.getValues) do not count against SOQL governor limits. This is the killer feature: configuration lookups in tight loops, trigger handlers, or batch processing do not blow the 100-query-per-transaction limit. Custom Settings beat custom objects for any data that gets read frequently and rarely changes.
Hierarchy resolution: org, profile, user
Hierarchy Custom Settings resolve in priority order: User-specific record (highest priority), then Profile-specific record, then Organization-level record (lowest priority). Apex calls MyHierarchySetting__c.getInstance(UserInfo.getUserId()) and the platform returns the most specific value defined for that user. This is the cleanest way to build per-user feature flags or per-profile defaults. The setting type cannot be changed from List to Hierarchy or vice versa after creation; pick the right type up front.
Editable in production via Setup UI
Unlike Custom Metadata Types, which require a metadata deployment to change values in production, Custom Settings can be edited directly through the Setup UI by admins. Tax rates need updating? Open the List Custom Setting, edit the record, save. No code deployment. This is the main reason Custom Settings persist in production orgs despite Custom Metadata Types being the modern alternative; admin-editable configuration in production is still important for many operational scenarios.
Limits and storage considerations
Each Custom Setting record counts against data storage just like custom object records. The total cached size of all Custom Settings per certified managed package is 10 MB; the total across the org is 10 MB times the number of installed managed packages. Records over this cap fall back to non-cached reads, defeating the performance benefit. Plan field counts and record volumes carefully; List Custom Settings with thousands of records are usually better expressed as a custom object with appropriate indexing.
Custom Settings versus Custom Metadata Types
Custom Metadata Types replaced Custom Settings as the recommended pattern for most new configuration. Metadata types deploy through change sets, version in source control, and support cross-object relationships and protected metadata visibility. Custom Settings keep the edge in one critical area: User and Profile hierarchy resolution, which Custom Metadata Types cannot do natively. The modern guidance is: use Custom Metadata Types for static configuration, use Hierarchy Custom Settings for per-user or per-profile overrides, and use List Custom Settings only when you need production admin editing without deployments.
Common patterns and anti-patterns
Good patterns: integration endpoint URLs in Hierarchy Custom Settings (different per environment), feature flag toggles per user, tax rate lookups by country in a List Custom Setting. Anti-patterns: large reference tables (use a custom object with indexing instead), secret API keys stored as plain text fields (use Named Credentials or Protected Custom Settings instead), and configuration tied to a specific deployment artifact (use Custom Metadata Types so the configuration travels with the code).
How to create and use a Custom Setting
Creating a Custom Setting is straightforward but the design choice matters. Pick List versus Hierarchy based on whether different users or profiles need different values. Plan the field types up front because they are hard to change later. Decide between standard Custom Setting and Protected Custom Setting based on whether the data is sensitive.
- Decide List versus Hierarchy and Public versus Protected
List for multiple named records (tax rates, feature lookups). Hierarchy for per-user, per-profile, or org-level overrides. Public for normal access, Protected for managed-package-only access. The type cannot be changed after creation.
- Create the Custom Setting in Setup
Setup > Custom Settings > New. Enter a label and API name, select List or Hierarchy, set Visibility (Public or Protected). Save. The setting now appears like a custom object in Object Manager.
- Add custom fields
Open the Custom Setting in the Custom Settings page > New > add fields. Text, Number, Currency, Date, Date/Time, Checkbox, Email, Phone, URL, and Percent are all supported. Picklist and lookup fields are not supported on Custom Settings.
- Populate records via Manage button (List)
Setup > Custom Settings > the setting > Manage > New. For List Custom Settings, each record needs a Name (the primary key) and the field values. For Hierarchy, each record is tied to Organization, a specific Profile, or a specific User.
- Reference from Apex with cached methods
MyListSetting__c rate = MyListSetting__c.getInstance(''US''); for List. MyHierarchySetting__c.getInstance() for Hierarchy with automatic user resolution. .getAll() returns the full map for List Custom Settings. None of these count against SOQL limits.
- Reference from Flow
Use the Get Records element with the Custom Setting object. Flow does not have the cached APIs that Apex has, so each Flow read costs a SOQL query. Cache the result in a Flow variable if accessed multiple times.
- Reference from formulas and validation rules
$$Setup.MyHierarchySetting__c.Field__c$$ in formula fields and validation rules pulls the current user's value through Hierarchy resolution. The $$Setup global is the formula-engine entry point to Hierarchy Custom Settings.
- Deploy the Custom Setting metadata and records
Custom Setting definition deploys via change set or metadata API like any custom object. Records deploy via Data Loader or as part of a deployment package (newer Salesforce CLI commands support Custom Setting record deployment).
List for flat record sets, Hierarchy for per-user/profile/org inheritance. Cannot be changed after creation.
Public is org-accessible. Protected restricts access to the managed package that defines it. Choose based on whether external code should read the values.
Text, Number, Currency, Date, Checkbox, and similar primitive types. No picklists, lookups, or rich text. Picklist substitution uses formula-based decoding instead.
- The setting type (List or Hierarchy) cannot be changed after creation. Plan the right type up front, because converting requires recreating the setting and migrating data.
- Custom Settings do not support picklist or lookup fields. Use a text field with predefined values or a formula that decodes a text key to a known value.
- Hierarchy Custom Settings cannot be referenced via Custom Metadata Type APIs. If you need per-user inheritance, Custom Settings remain the only native option.
- The 10 MB per-package cache limit caps the practical size of Custom Settings. Large reference tables exceed this and fall back to non-cached reads, defeating the performance benefit.
- Flow reads of Custom Settings do count against SOQL governor limits because Flow does not use the Apex cached APIs. Cache results in Flow variables if accessed repeatedly.
Trust & references
Cross-checked against the following references.
- Custom Settings OverviewSalesforce Help
- Custom Settings Apex MethodsSalesforce Developer
- Custom Metadata Types OverviewSalesforce Help
Straight from the source - Salesforce's reference material on Custom Settings.
- Custom SettingsSalesforce Help
- Create Custom SettingsSalesforce Help
- Apex Methods for Custom SettingsSalesforce Developer
Hands-on resources to go deeper on Custom Settings.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What are the two types of Custom Settings?
Q2. What's a key advantage of Custom Settings over regular custom objects?
Q3. When should you use Custom Metadata Types instead of Custom Settings?
Discussion
Loading discussion…