Skip to content

Swapnil Zambare - Blog

  • Home
  • Salesforce
    • Salesforce Admin
    • Salesforce Developer
    • Salesforce Interview
    • Developer Interview
  • Trailmix
  • Sitemap
  • About

Read this page in

    Translated by Google. Machine translation can contain mistakes.

    Home » Hierarchy Custom Settings in Apex Explained with Examples
    Level: IntermediateSalesforce

    Hierarchy Custom Settings in Apex Explained with Examples

    Swapnil Zambare·October 20, 2026·Updated November 15, 2026·8 min read
    Hierarchy Custom Settings featured image: code editor card with getInstance call
    On this page
    1. What are Hierarchy Custom Settings?
    2. Why Hierarchy Custom Settings Matter
    3. How Hierarchy Custom Settings Work
    4. Creating the Setting
    5. Reading the Merged Value
    6. Reading a Specific Level
    7. Writing a Setting from Apex
    8. Hierarchy Custom Settings Methods
    9. Hierarchy vs List Custom Settings
    10. A Real Hierarchy Custom Settings Example
    11. Step 1: Set the Values
    12. Step 2: Enforce It in Apex
    13. Step 3: Use It in a Trigger
    14. Step 4: Check the Result
    15. Common Mistakes with Hierarchy Custom Settings
    16. Best Practices for Hierarchy Custom Settings
    17. Practice Task
    18. Most Asked Hierarchy Custom Settings Interview Questions
    19. Basic Hierarchy Custom Settings Interview Questions
    20. Intermediate Hierarchy Custom Settings Interview Questions
    21. Advanced Hierarchy Custom Settings Interview Questions
    22. Official Resources
    23. Quick Recap
    24. What’s Next?

    Hierarchy Custom Settings let you store a value once for the whole org, then override it for a profile or even a single user. So you can turn a feature off for everyone, leave it on for the admin team, and read the right answer in Apex with one line and no query.

    This post builds on Custom Metadata Types vs Custom Settings and Apex classes. We will control fee rules at Bright Path Tutors.

    What are Hierarchy Custom Settings?

    Hierarchy Custom Settings are a custom setting type with three levels: organization, profile and user. Salesforce merges them for you, so the most specific value wins. They live in cache, which is why reading them costs no SOQL.

    Think of a school dress code. The school sets one rule, a department may change part of it, and one student may have a medical exemption. You always follow the most specific rule that applies to you.

    Why Hierarchy Custom Settings Matter

    Hard-coded numbers age badly. A discount cap, a batch size or a debug switch written into Apex needs a deployment every time it changes.

    Hierarchy Custom Settings move those values into Setup. Also, because they do not count against SOQL limits, you can read them inside loops and triggers without worry.

    How Hierarchy Custom Settings Work

    With Hierarchy Custom Settings, Salesforce looks for the most specific record and falls back if it does not find one.

    Hierarchy Custom Settings diagram showing user, profile and org fallback
    How the user, profile and org levels are merged.

    Creating the Setting

    An admin creates it in Setup under Custom Settings, choosing Hierarchy as the type. Each field becomes a value you can override.

    FieldTypePurpose
    Max_Discount__cPercentHighest discount this user may give
    Enable_Auto_Email__cCheckboxTurns reminder emails on or off
    Batch_Size__cNumberRecords per batch run

    Reading the Merged Value

    // Merged for the running user
    Fee_Setting__c s = Fee_Setting__c.getInstance(UserInfo.getUserId());
    System.debug('Max discount: ' + s.Max_Discount__c);
    System.debug('Auto email: ' + s.Enable_Auto_Email__c);

    With no argument, getInstance() also returns the merged value for the current user, which is the common case.

    Fee_Setting__c s = Fee_Setting__c.getInstance();

    Reading a Specific Level

    Sometimes you want the org value even when the user has an override.

    Fee_Setting__c org = Fee_Setting__c.getOrgDefaults();
    Fee_Setting__c forProfile = Fee_Setting__c.getInstance(profileId);
    Fee_Setting__c forUser = Fee_Setting__c.getInstance(userId);

    The debug for a user whose profile allows more than the org default looks like this.

    Org default: 10
    Profile value: 20
    Merged for user: 20

    Writing a Setting from Apex

    Custom settings are records, so normal DML works.

    Fee_Setting__c s = Fee_Setting__c.getOrgDefaults();
    if (s.Id == null) {
        s = new Fee_Setting__c(SetupOwnerId = UserInfo.getOrganizationId());
    }
    s.Max_Discount__c = 15;
    upsert s;

    SetupOwnerId is the field that decides the level. It holds the org Id, a profile Id or a user Id.

    Hierarchy Custom Settings Methods

    This table lists the methods you get for free.

    MethodReturns
    getInstance()Merged value for the running user
    getInstance(userId)Merged value for that user
    getInstance(profileId)Merged value for that profile
    getOrgDefaults()The organization level record only
    getValues(name)Used by list settings, not hierarchy

    Hierarchy vs List Custom Settings

    Custom settings come in two types. This table compares them.

    FeatureHierarchyList
    LevelsOrg, profile, userOne flat list
    OverridesYesNo
    Lookup bygetInstancegetValues with a name
    Best forSwitches and limitsReference data
    Counts against SOQLNoNo
    Hierarchy Custom Settings compared with list custom settings
    Hierarchy compared with list custom settings.

    In short, use hierarchy when the answer depends on who is running the code. Use list settings for shared reference data.

    A Real Hierarchy Custom Settings Example

    Bright Path lets counsellors give a discount, but the cap differs. Normal staff may give 10%, team leads 20%, and one senior counsellor is allowed 25%.

    Step 1: Set the Values

    An admin enters three records in Setup.

    LevelWhoMax Discount
    OrganizationEveryone10
    ProfileTeam Lead20
    UserRavi Kumar25

    Step 2: Enforce It in Apex

    public with sharing class DiscountGuard {
        public static Boolean isAllowed(Decimal requested) {
            Fee_Setting__c s = Fee_Setting__c.getInstance();
            Decimal cap = (s != null && s.Max_Discount__c != null)
                          ? s.Max_Discount__c : 0;
            return requested <= cap;
        }
    }

    The null check matters. If no record exists at any level, getInstance returns an empty object rather than null, and the fields are null.

    Step 3: Use It in a Trigger

    for (Enrolment__c e : Trigger.new) {
        if (e.Discount_Percent__c != null && !DiscountGuard.isAllowed(e.Discount_Percent__c)) {
            e.addError('Discount above your allowed limit.');
        }
    }

    Because the read costs no SOQL, calling it inside the loop is safe. Even so, reading it once before the loop is tidier.

    Step 4: Check the Result

    System.debug(DiscountGuard.isAllowed(8));
    System.debug(DiscountGuard.isAllowed(22));

    Running as Ravi, who is capped at 25, both come back true.

    true
    true

    Running as a normal counsellor, the second one is false.

    Common Mistakes with Hierarchy Custom Settings

    • Assuming getInstance returns null when nothing is set, instead of an empty record.
    • Forgetting SetupOwnerId when creating a record in Apex.
    • Storing secrets such as API keys, which are visible to anyone who can read the setting.
    • Using a custom setting where Custom Metadata would deploy more cleanly.
    • Creating a user level record for every user, which becomes hard to maintain.

    Best Practices for Hierarchy Custom Settings

    • Always set an organization default so there is a safe fallback.
    • Keep overrides rare, usually at profile level rather than user level.
    • Null check every field before you use it.
    • Read the setting once per transaction and pass it around.
    • Use Custom Metadata when the value should move between orgs with your code.

    Practice Task

    Create a hierarchy setting with a checkbox called Enable_Debug__c. Set it off at org level and on for your own user. Then write a method that returns its value. Hint: use getInstance with no arguments.

    Most Asked Hierarchy Custom Settings Interview Questions

    These Hierarchy Custom Settings questions test whether you know how configuration should be stored.

    Basic Hierarchy Custom Settings Interview Questions

    Q1: What are hierarchy custom settings?

    Hierarchy Custom Settings store values at org, profile and user level, and Salesforce returns the most specific match.

    Q2: What are the two types of custom setting?

    Hierarchy Custom Settings and list settings. Hierarchy supports overrides, while list settings are a flat set of named records.

    Q3: Which method returns the merged value?

    getInstance, either with no argument for the running user or with a user or profile Id.

    Q4: What does getOrgDefaults return?

    Only the organization level record, ignoring any profile or user override.

    Q5: Do custom settings count against SOQL limits?

    No. They are held in cache, so reading them is free.

    Q6: What field decides the level of a record?

    SetupOwnerId, which holds an org, profile or user Id.

    Q7: Can you update a custom setting in Apex?

    Yes. They are records, so insert, update and upsert all work.

    Q8: What does getInstance return when nothing is set?

    An empty record with null fields, not null itself.

    Intermediate Hierarchy Custom Settings Interview Questions

    Q9: What is the order of precedence?

    User beats profile, and profile beats the organization default.

    Q10: Why read the setting once per transaction?

    Although reads are cheap, repeated calls still cost CPU time. One read and a local variable is cleaner.

    Q11: Can hierarchy settings be deployed with data?

    The definition deploys, but the records do not. So you recreate values per org or load them with a script.

    Q12: How is Custom Metadata different?

    Custom Metadata records deploy with your code and can be referenced in formulas and validation rules. However, it has no user level override.

    Q13: Should you store API keys in a custom setting?

    No. Use Named Credentials or protected Custom Metadata, since custom settings are readable by many users.

    Q14: Can a formula field reference a hierarchy setting?

    Yes. Formulas and validation rules can reference custom setting fields, which is a common reason to choose them.

    Q15: What happens when a user has no profile override?

    The merged value falls back to the organization default automatically.

    Q16: Are custom settings available in a Flow?

    Yes. Flow can reference custom setting values directly in formulas and decisions.

    Advanced Hierarchy Custom Settings Interview Questions

    Q17: Scenario: a feature must be off in production but on for testers. How?

    Set the checkbox off at org level, then add user level records for the testers. No deployment is needed to change it later.

    Q18: What are the storage limits?

    Custom settings share a cached data limit per org, often a few megabytes. So keep them small and avoid large lists.

    Q19: Scenario: a setting is missing in a new sandbox. What breaks?

    Any code that assumes a value. Therefore always null check and provide a code level default.

    Q20: When would you choose Custom Metadata instead?

    When values must travel with the deployment, be packaged, or be referenced across orgs without manual setup.

    Q21: How do you test code that reads a custom setting?

    Insert the setting record in the test with the right SetupOwnerId, so the test does not depend on org data.

    Q22: Why is a user level record per user a bad pattern?

    Because maintenance grows with headcount. Profile level overrides scale far better.

    Q23: Can custom settings be protected in a package?

    Yes. A protected setting is visible only to code in the package, which suits internal switches.

    Q24: How do hierarchy settings behave for guest users?

    They fall back to the guest user profile or the org default, so set a safe org value.

    Q25: Are Hierarchy Custom Settings cached per user?

    The cache is per org, but the merged result depends on who is running. So two users can read different values from the same setting.

    Q26: Can a trigger write to Hierarchy Custom Settings?

    Yes, since they are records and normal DML applies. However, writing on every save adds DML, so do it sparingly.

    Q27: Do Hierarchy Custom Settings respect field level security?

    Setup access controls who can edit them, and code reading them runs in system context. Therefore do not rely on them to hide sensitive values.

    Q28: Scenario: a batch size must differ per environment. Which tool?

    Hierarchy Custom Settings work, since the value stays per org. Alternatively Custom Metadata with an environment field also fits.

    Q29: How do you migrate Hierarchy Custom Settings data to production?

    Export the records and load them with Data Loader, or create them in a post-deployment script, because the data does not deploy.

    Official Resources

    • Apex Developer Guide: Custom Settings
    • Salesforce Help: Custom Settings
    • Salesforce Help: Custom Metadata Types

    Quick Recap

    • Hierarchy Custom Settings merge org, profile and user values.
    • getInstance returns the most specific match for the running user.
    • Reads cost no SOQL, so they are safe inside loops.
    • getInstance never returns null, so null check the fields.
    • Use Custom Metadata when values must deploy with your code.

    What’s Next?

    Next, we protect data in code with Apex Crypto and Encoding.

    • Apex
    • Certification
    • Custom Metadata
    • Intermediate

    Share this article

    • LinkedIn
    • X
    • WhatsApp
    • Email

    Written by

    Swapnil Zambare

    Post navigation

    PreviousApproval Processes in Apex: Submit, Approve and Recall in Code
    NextApex Crypto and Encoding: Hashing, AES and Base64 Explained

    On this page

    1. What are Hierarchy Custom Settings?
    2. Why Hierarchy Custom Settings Matter
    3. How Hierarchy Custom Settings Work
    4. Creating the Setting
    5. Reading the Merged Value
    6. Reading a Specific Level
    7. Writing a Setting from Apex
    8. Hierarchy Custom Settings Methods
    9. Hierarchy vs List Custom Settings
    10. A Real Hierarchy Custom Settings Example
    11. Step 1: Set the Values
    12. Step 2: Enforce It in Apex
    13. Step 3: Use It in a Trigger
    14. Step 4: Check the Result
    15. Common Mistakes with Hierarchy Custom Settings
    16. Best Practices for Hierarchy Custom Settings
    17. Practice Task
    18. Most Asked Hierarchy Custom Settings Interview Questions
    19. Basic Hierarchy Custom Settings Interview Questions
    20. Intermediate Hierarchy Custom Settings Interview Questions
    21. Advanced Hierarchy Custom Settings Interview Questions
    22. Official Resources
    23. Quick Recap
    24. What’s Next?

    Keep reading

    Level: BeginnerSalesforce

    Salesforce Developer Topics: Study Guide and Full List of Posts

    November 22, 2026·11 min read
    Level: IntermediateDeveloper Interview Questions

    Developer Interview Questions Index: Every Salesforce Developer Topic in One Place

    November 22, 2026·9 min read
    Level: BeginnerAdmin Interview Questions

    Salesforce Interview Questions: All Posts by Topic and Role

    November 22, 2026·9 min read

    © 2026 Swapnil Zambare - Blog

    Theme: Swapz Modern UI by Swapnil Zambare

    • LinkedIn
    • GitHub
    • X
    • Trailblazer
    • RSS