Custom Metadata Types Salesforce Guide

Author : Selavina Brookvale
Date: September 2, 2025

Introduction

Custom Metadata Types in Salesforce (CMDTs) are one of the most powerful tools for building scalable, configurable applications. Unlike custom settings, CMDTs are deployable, packageable, and version-controlled, making them ideal for enterprise-grade Salesforce projects.

They allow you to define reusable configurations, business rules, feature toggles, and integration endpoints without hardcoding values. This guide explains what Custom Metadata Types are, how they differ from Custom Settings, their key use cases, setup process, and best practices.

What Are Custom Metadata Types in Salesforce?

Alt text: Salesforce Setup showing Custom Metadata Types list in desktop mockup.

Custom Metadata Types (suffix __mdt) let you define application configuration as metadata. Both the type and its records can be deployed across environments.

They support fields, validation rules, and relationships.
CMDT records are cached at runtime, so retrieving them doesn’t count against SOQL governor limits.
They integrate seamlessly with Apex, Flow, and formulas, enabling both declarative and programmatic use.

Custom Metadata Types vs Custom Settings

Feature	Custom Metadata Types (CMDTs)	Custom Settings
Deployable with records	Yes	No
Packageable for AppExchange	Yes	No
Supports validation & formulas	Yes	No
Cached (no SOQL needed)	Yes	No
Best for	Reusable configuration	Org-specific values

For most Salesforce configuration metadata, CMDTs are the better option.

Related reading: Salesforce Record-Level Security

Key Use Cases of Custom Metadata Types

Custom Metadata Types in Salesforce go far beyond simple configuration. They allow admins and developers to store business rules, reference data, and environment-specific settings directly as metadata. This means values are not only reusable but also deployable across sandboxes, staging, and production environments without manual re-entry.

Whether you’re managing feature toggles, lookup tables, integration endpoints, or security rules, CMDTs provide a scalable and version-controlled solution that reduces hardcoding and simplifies maintenance.

1. Configuration & Feature Management

https://sdlccorp-web-prod.blr1.digitaloceanspaces.com/wp-content/uploads/2025/09/01180509/Untitled-design-54.webp.

CMDTs are perfect for feature toggles and environment-specific rules. Instead of editing Apex, you switch features on/off through CMDT records.

2. Data Mappings & Lookup Tables

Salesforce CMDT records list for tax rate mapping in desktop mockup.

CMDTs can store reference data such as tax brackets, endpoint URLs, or region codes. This makes them reusable across orgs.

3. Integration with Apex, Flows, and Formulas

Salesforce Developer Console showing Apex code using Custom Metadata Types

Apex: Access with getAll() and getInstance().
Flows: Reference CMDT values in automation.
Formulas: Use $CustomMetadata to replace hardcoded values.

4. Business Rules & Defaults

Store thresholds, limits, and default values in CMDTs for maintainable logic across orgs.

Step-by-Step Setup: Creating Custom Metadata Types

The advantages of AI in HR go beyond time savings. They shape strategy and workforce experience.

Step 1 — Create the CMDT

Salesforce new Custom Metadata Type creation screen in desktop mockup.

Go to Setup → Custom Metadata Types → New.
Enter Label: Feature Toggle.
Object Name: Feature_Toggle.
Save.

Step 2 — Add Fields

Add custom fields such as:

Feature_Key__c (Text)
Is_Enabled__c (Checkbox)
Description__c (Text Area)

Step 3 — Set Visibility

Public: Usable across subscriber orgs.
Protected: Restricted to package namespace.

Step 4 — Create Records

Salesforce CMDT manage records screen for Feature Toggle in desktop mockup.

Click Manage Records and add entries like:

Checkout_Discounts → Is_Enabled = TRUE
Beta_UX → Is_Enabled = FALSE

Step 5 — Use CMDT in Apex

Salesforce Developer Console showing Apex code using CMDT getInstance.

CMDTs can be accessed in Apex without SOQL (faster, doesn’t consume governor limits).

Example 1: Single record

Example 2: All records

Example 3: SOQL (for long text fields)

Step 6 — Use CMDT in Formulas & Flows

Salesforce Flow Builder referencing Custom Metadata Types in desktop mockup.

Formula Example

👉 Useful for validation rules or default values.

Flow Example

Create a Flow.
Add a Decision Element.
Reference $CustomMetadata.Feature_Toggle__mdt.
Choose Is_Enabled__c for decision logic.

Flows can now change behavior based on metadata.

Step 7 — Test CMDTs in Apex

Salesforce Apex test class using CMDT in desktop mockup.

CMDTs are available by default in tests.

Step 8 — Deploy CMDTs Across Environments

Salesforce Change Set screen showing deployment of CMDT in desktop mockup..

Change Sets → point-and-click migration.
Salesforce CLI (sfdx) → for CI/CD pipelines.
Unlocked Packages → best for large teams.

Always deploy CMDT + records together.

Best Practices for Custom Metadata Types

Name fields clearly → e.g., Feature_Key__c.
Keep CMDTs lightweight → only store values needing deployment.
Use static accessors in Apex → avoid unnecessary queries.
Add validation rules → prevent incorrect metadata.
Version-control metadata → commit CMDTs to Git with other metadata.

Benefits of Using Custom Metadata Types

Salesforce desktop mockup showing dashboard panel listing benefits of Custom Metadata Types such as scalability, maintainability, performance, and flexibility.

Scalability → works across orgs and packages.
Maintainability → avoids hardcoding.
Performance → cached, no SOQL needed.
Flexibility → usable in Apex, Flows, Formulas.

Conclusion

Salesforce Custom Metadata Types give developers and admins a powerful way to manage configurations declaratively. They reduce code maintenance, improve scalability, and help enforce governance.

For feature toggles, mappings, integration settings, and reusable business rules, CMDTs should be your go-to choice.

FAQs

Q1: What are Custom Metadata Types in Salesforce?

Custom Metadata Types (CMDTs) are metadata objects (__mdt) used to store configuration as metadata. They help developers and admins manage reusable values, rules, and settings that can be deployed across orgs.

Q2: How do Custom Metadata Types differ from Custom Settings?

CMDTs are deployable with records, packageable, and support validation rules and formulas. Custom Settings are limited to org-specific data, making CMDTs the better choice for scalable configuration.

Q3: What are the main use cases of Custom Metadata Types?

CMDTs are best for feature toggles, lookup tables, integration endpoints, business rules, and environment-specific settings. They remove hardcoding and improve governance.

Q4: Can I use Custom Metadata Types in Apex code?

Yes. CMDTs can be accessed using getAll() or getInstance() methods in Apex without consuming SOQL queries. For long text fields, you can use SOQL queries on __mdt objects.

Q5: How can Custom Metadata Types be used in Flows and Formulas?

CMDTs can be referenced in Flows via Decision Elements and in formulas using $CustomMetadata. This allows admins to configure automation without hardcoding values.

Q6: Are CMDTs available in all Salesforce editions?

Yes. Custom Metadata Types are available in Enterprise, Performance, Unlimited, and Developer editions.

Q7: Do CMDTs count against SOQL governor limits?

Yes. Custom Metadata Types are available in Enterprise, Performance, Unlimited, and Developer editions.

Selavina Brookvale

Selavina Brookvale, a Salesforce expert with 12 years’ experience, specializes in Sales, Service, and Marketing Cloud. She helps businesses optimize CRM strategies, delivers impactful solutions, and shares insights to guide the Salesforce community toward innovation and measurable success.

Subscribe Our Newsletter

Request A Proposal