If you have ever deployed a Salesforce change only to realize the picklist values are still wrong in production, or you had to submit another deployment just to tweak a single setting, you are not alone. Most admins and developers have been there. What if you could decouple configuration from code entirely?

What Are Custom Metadata Types?

Custom Metadata Types are essentially customizable application settings that live inside Salesforce metadata. Unlike Custom Settings (which are data records stored in the database), Custom Metadata Types are metadata — they are deployed via change sets, packages, or CLI, they participate in version control, and they do not count toward your data storage limits.

Think of them as a schema you define — like an sObject — where every record you create under that schema is treated as metadata rather than data. That distinction unlocks everything that makes them powerful.

Why Use Custom Metadata Types Instead of Custom Settings?

This is the most common question. Here is the short answer:

• Deployable — CMDTs ship with your metadata. Custom settings records do not. You manage them through the UI or API separately.
• Versionable — Because they live in source control, you can diff changes, roll back, and audit who changed what.
• Queryable in SOQL — Same as custom settings, but you can also reference them in validation rules, formula fields, and Apex without a SOQL query.
• No storage limits — CMDTs bypass your data storage allocation entirely.
• Protected components — You can mark fields and records as protected so managed packages can ship them without exposing internals.

Real-World Use Cases

1. Third-Party API Configuration

Store endpoint URLs, API keys (referenced securely), timeout values, and retry logic parameters. When the API provider changes their base URL, you update one record — no deployment required. The Apex code reads from the CMDT at runtime.

2. Picklist Value Governance

Define allowed values, descriptions, and active/inactive flags in a CMDT. Your validation rule cross-references it. Business users can request new values via a simple approval process — an admin updates the CMDT record, done. No more picklist value deployments.

3. Business Rule Engines

Discount tiers, SLA timeframes, lead scoring thresholds, territory assignment rules. Store the parameters in CMDTs, run the logic in Apex. Changing a threshold from 90 to 80 points? Update one record, push to prod as metadata, and you are done.

4. Multi-Tenant Feature Toggles

If you are building managed packages or AppExchange solutions, CMDTs let you ship protected configuration that subscribers can override selectively — without breaking upgrade paths.

How to Build One in 5 Minutes

Let us walk through creating a simple API Configuration CMDT:

1. Setup → Custom Metadata Types → New Custom Metadata Type
2. Label: API Configuration, Plural Label: API Configurations
3. Add fields: Endpoint_URL__c (URL), API_Key__c (Encrypted), Timeout_Seconds__c (Number), Retry_Count__c (Number)
4. Create records for each API integration — Dev, Staging, Production URLs stored per environment.
5. Reference in Apex with API_Configuration__mdt.getInstance('Stripe_Prod')

That is it. You now have deployable, versionable, environment-aware configuration that you can update without touching code.

A Quick Tip on Environment Management

A common pattern is to suffix CMDT record names by environment: Stripe_Dev, Stripe_UAT, Stripe_Prod. Then a single Apex helper method resolves the right one based on your org profile or a top-level CMDT that defines the current environment. This keeps your deployment pipeline clean and your configuration transparent.

Limitations Worth Knowing

• CMDT records are read-only at runtime — you cannot update them via Apex DML or SOAP API. If you need config that users can self-serve, Custom Settings or custom objects are the better fit.
• There is a 10 MB total size limit for all CMDT records in an org. This is rarely an issue but worth knowing if you are storing large volumes.
• No relationships — CMDTs do not support master-detail or lookup relationships to other records.

When to Use What?

Here is a simple decision framework:

• Configuration that changes with deployments → Custom Metadata Type
• Configuration users modify daily → Custom Settings or Custom Object
• Configuration per user → Hierarchy Custom Setting
• Configuration shipped in a managed package → Custom Metadata Type (protected)

Custom Metadata Types are one of those Salesforce features that quietly makes everything better once you start using them. They bridge the gap between hardcoded constants and freeform database records, giving you the best of both worlds: deployable, versionable configuration that is still flexible at runtime.

If you are not using them yet, start with something small — your API endpoints or picklist values — and watch how much cleaner your deployments get.

Have a clever use case for Custom Metadata Types we missed? Drop it in the comments or reach out to MotionDog — we love nerding out about Salesforce architecture.