Skip to main content

Get Started with Custom Metadata Types

Learning Objectives

After completing this unit, you’ll be able to:

  • Define custom metadata types.
  • Describe the differences between custom settings and custom metadata types.
  • Identify several use cases for custom metadata types. 

Before You Begin

To get the most out of this module, you should be familiar with the fundamentals of creating objects, modeling data, and setting permissions. For an introduction to the basics, or for a refresher, complete the Data Modeling and Data Security modules here on Trailhead before you continue in this module.

What Is a Custom Metadata Type?

Let’s start from the beginning: What is metadata? Metadata is data that describes other data. For example, in a Salesforce org, there’s a standard object called Account. The structure of that object is metadata. When you add a record with a customer’s contact information to an Account, you’re adding data. Field names, such as first name and last name are metadata. The values in those fields, for example, Amy and Lane are data.

So, what is a custom metadata type? A custom metadata type is an object that's used to define the structure for application metadata. The fields of custom metadata types, and the values in the fields, consist only of metadata. The records of custom metadata types are also metadata, not data.

Using metadata is pretty handy because it can be imported into Salesforce, modified in the interface, and manipulated using the Metadata API. Instead of storing hard-coded data, custom metadata types let you configure apps by building reusable functionality that determines the behavior based on metadata. And you can do much of this customization work using declarative tools.

When you deploy apps with custom metadata types, all of the records and fields are included in the package installation, so no additional steps are needed. You can deploy custom metadata types from a sandbox with change sets or packaged in managed packages.

Unlike custom metadata types, when you deploy apps with custom objects and custom settings, the metadata for those objects (the header) gets deployed, but the records (definitions) are left behind. Whether you’re manually loading records or inserting records using an Apex script, adding records can be a time-consuming process.

Two tables highlighting what is packaged and deployed. All of the Custom Metadata Types table is selected but only the first row (the header) of the Custom Objects/Custom Settings table is selected.

Differences Between Custom Metadata Types and Custom Settings

Both custom metadata types and custom settings can be used for list data like a list of VAT rates or support levels. Custom settings can be configured as a hierarchy where custom settings values are made available to specific users, profiles, or org levels.

Custom Metadata Types 

Custom Settings 


Handles list data. Doesn't support hierarchy type data based on user, profile, or org level.

Similar to custom objects. You can either create a list- based or hierarchy-based custom setting.


Records can be packaged and deployed. Can also be deployed via Metadata API or change sets.

Records can’t be deployed using a package, Metadata API, or change sets.

Relationship Field

Supports lookups between custom metadata types.

Doesn’t support relationship fields.



“_c” like a custom object.

CRUD in Apex

Supports full CRU (create, read, update) operations in Apex. Delete isn’t supported.

Supports full CRUD (create, read, update, delete) operations in Apex.

Use Cases for Custom Metadata Types

Here are some examples of what you can do with custom metadata types.

  • Mappings: You can use custom metadata types to create associations between different objects. For example, you can create a custom metadata type that assigns cities, states, or provinces to particular regions in a country.
  • Business rules: Salesforce has lots of ways to define business rules. One way is to combine configuration records with custom functionality. For example, you can use custom metadata types along with some Apex code to route payments to the correct endpoint.
  • Primary data: Say that your org uses a standard accounting app. You can create a custom metadata type that defines custom charges, like duties and VAT rates. If you include this type as part of an extension package, subscriber orgs can reference this primary data. 

More About Custom Metadata Types

Custom metadata types support most standard field types, including:

  • Metadata Relationships
  • Checkbox
  • Date and Date/Time
  • Email and Phone
  • Number
  • Percent
  • Picklist
  • Text and Text Area
  • URL

Developer Support

Developers can use SOQL to read custom metadata types. To create or update metadata records, they can use the Metadata API. Apex code can create, read, and update (but not delete) custom metadata records.

Reference Custom Metadata Types

Custom metadata types can be used directly from:

  • Apex
  • Flows
  • Formula fields
  • Validation rules

Custom metadata types are customizable, deployable, packageable, and upgradeable application metadata. In many cases, custom metadata types have an advantage over custom settings and custom objects. They can make your application lifecycle management and compliance easier, faster, and more robust. In the next unit, you create your own custom metadata type.


Keep learning for
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities