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.