Custom Settings
Custom Settings in Salesforce are a special type of custom object that allows administrators and developers to store reusable configuration data at the organization, profile, or user level.
Definition
Custom Settings in Salesforce are a special type of custom object that allows administrators and developers to store reusable configuration data at the organization, profile, or user level. There are two types: List Custom Settings (store a dataset accessible across the org) and Hierarchy Custom Settings (store settings that can be overridden at the profile or user level). Custom Settings data is cached in the application cache, enabling fast access without SOQL queries.
In plain English
“Custom Settings are a special kind of object for storing configuration data that your code can read quickly without running SOQL queries. There are two flavors: List Custom Settings (one set of values for the whole org) and Hierarchy Custom Settings (values that can be overridden per profile or per user).”
Worked example
A developer at Hartmoor Capital uses Custom Settings to store integration credentials and feature-flag configuration. List Custom Settings hold a flat reference table of API endpoint URLs (one per environment); Hierarchy Custom Settings hold per-profile feature flags (FeatureX_Enabled with org default = OFF, profile override = ON for the beta-testers profile). Apex code reads Custom Settings via getInstance() or getValues() - the data is cached, so reads don't consume SOQL queries. Custom Settings replace what would otherwise be hardcoded constants in code, making configuration changeable without redeploys.
Why Custom Settings matters
Custom Settings are a specialized type of custom object designed for storing configuration data that code reads frequently. Unlike regular custom objects, Custom Settings are cached in the application cache, so Apex code can read values using methods like getInstance() without consuming SOQL query limits. This makes them well-suited for configuration that's accessed often: feature flags, default values, thresholds, and lookup data that gets read on every request.
There are two types. List Custom Settings store a set of records accessible across the org, like a list of valid country codes or tax rates. Hierarchy Custom Settings store values that can be overridden at different levels: the org default, specific profiles, and specific users. When code requests a value, the platform returns the most specific one it finds. Hierarchy Custom Settings are useful when different user populations need different configuration without building separate logic. Custom Metadata Types have mostly replaced Custom Settings for configuration that should deploy with code, but Custom Settings remain useful when you need runtime editability per profile or per user.
How to create Custom Settings
Custom Settings are a specialized object type for storing org-wide / profile-level / user-level configuration data — feature flags, integration endpoints, default values your code reads frequently. They're cached in the application cache for fast access without SOQL. Two flavors: List (org-wide dataset) and Hierarchy (per-org/profile/user fallback).
- Open Setup → Custom Settings
Setup gear → Quick Find: Custom Settings → Custom Settings.
- Click New
Top-right.
- Set Label and Object Name
Label is admin-facing; Object Name is the API (auto-derived, with __c suffix).
- Pick Setting Type: List or Hierarchy
List: a single dataset accessed across the org by record name. Hierarchy: per-org / profile / user fallback for the same setting key. Locked after Save.
- Set Visibility: Protected or Public
Public: any subscriber can access. Protected: only the managed package owner. For internal Custom Settings, Public is fine.
- Save → add Custom Fields to the setting
Each Custom Setting needs fields to store actual values. Same field types as a Custom Object.
- Add records via the Manage button
On the Custom Setting detail page, Manage opens the records UI. List: each record has a unique Name. Hierarchy: each record is keyed by Profile / User / Default Org.
Required.
Required. __c suffix.
Required. List / Hierarchy.
- Custom Settings have been largely replaced by Custom Metadata Types for new development. Custom Metadata is deployable via Change Sets / DX (Custom Settings data isn't), making Custom Metadata the modern best practice for most config use cases.
- Hierarchy Custom Settings cascade Org → Profile → User. The most-specific value wins. Querying without specifying user/profile context returns the org-level default — surprising when you expected per-user.
- Custom Settings limits per edition apply (e.g., 50 Custom Settings per org in Enterprise Edition). Hit the limit and you need to consolidate or use Custom Metadata Types instead.
How organizations use Custom Settings
Uses Hierarchy Custom Settings to store per-user preferences for a custom app. The default is one setting, but specific profiles and users can override it, giving them flexibility without code changes.
Migrated feature flags from Hierarchy Custom Settings to Custom Metadata Types. The metadata approach fit their CI/CD process better, but they kept Hierarchy Settings for values that needed to be edited in production without a deployment.
Caches frequently-read lookup data (country codes, currency conversion rates) in List Custom Settings so Apex code can read the values without consuming query limits.
Trust & references
Straight from the source - Salesforce's reference material on Custom Settings.
- Create Custom SettingsSalesforce Help
- Manage Custom Settings DataSalesforce Help
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…