PlatformEventChannel Metadata Type Reference

The PlatformEventChannel metadata type defines a custom event channel (__chn) that external middleware (subscribing via the Pub/Sub API or CometD) can subscribe to in order to receive a dedicated, filtered stream of Change Data Capture (CDC) events, Custom Platform Events, or Real-Time Event Monitoring events.

In Salesforce DX projects, custom channels are stored in force-app/main/default/platformEventChannels/ with the .platformEventChannel-meta.xml suffix (for example, ERP_Order_Sync__chn.platformEventChannel-meta.xml).

Why Custom PlatformEventChannel Architecture Matters#

If you enable Change Data Capture on 15 objects in Setup, every subscriber listening to the default /data/ChangeEvents topic receives change events for all 15 objects—quickly exhausting daily event delivery allocations when multiple downstream systems (ERP, Data Warehouse, Billing) listen simultaneously. By provisioning dedicated PlatformEventChannel streams per downstream subscriber and pairing them with PlatformEventChannelMember filters, each consumer receives only the objects and rows it actually cares about.

Key Metadata Fields#

Production-Grade XML Examples#

1. Custom Change Data Capture Channel (ERP_Order_Sync__chn.platformEventChannel-meta.xml)#

Subscribed via /data/ERP_Order_Sync__chn:

<?xml version="1.0" encoding="UTF-8"?>
<PlatformEventChannel xmlns="http://soap.sforce.com/2006/04/metadata">
    <channelType>data</channelType>
    <label>ERP Order Sync CDC Channel</label>
</PlatformEventChannel>

2. Custom Platform Event Grouping Channel (Billing_Events__chn.platformEventChannel-meta.xml)#

Subscribed via /event/Billing_Events__chn (API version 61.0+):

<?xml version="1.0" encoding="UTF-8"?>
<PlatformEventChannel xmlns="http://soap.sforce.com/2006/04/metadata">
    <channelType>event</channelType>
    <eventType>custom</eventType>
    <label>Consolidated Billing Platform Events Channel</label>
</PlatformEventChannel>

Querying PlatformEventChannel via Tooling API#

-- List all custom PlatformEventChannels in the org (Tooling API)
SELECT Id, DeveloperName, MasterLabel, ChannelType, EventType
FROM PlatformEventChannel
ORDER BY MasterLabel ASC

Frequently asked questions

Why should I create a custom PlatformEventChannel instead of subscribing to the standard ChangeEvents channel?

Subscribing to the default /data/ChangeEvents channel delivers all CDC events across every enabled object in the org. Creating a custom PlatformEventChannel (such as SalesEvents__chn) lets you isolate specific entities, apply server-side stream filtering, and enrich events with extra fields.

What is the required naming suffix for a custom PlatformEventChannel?

Every custom PlatformEventChannel fullName and file name must end with the __chn suffix, such as ERP_Sync_Channel__chn.platformEventChannel-meta.xml.

Why was the channelMembers field removed from PlatformEventChannel in API version 47.0?

Starting in API version 47.0, Salesforce decoupled channel membership into a separate metadata type called PlatformEventChannelMember so individual object streams, enriched fields, and filter expressions can be deployed and deleted independently.

What are the valid combinations of channelType and eventType on a PlatformEventChannel?

Set channelType to data (with optional eventType data) for Change Data Capture channels. Set channelType to event (with eventType set to custom or monitoring in API v61.0+) for grouping custom Platform Events or Real-Time Event Monitoring events.

Can I retrieve or delete the standard ChangeEvents channel using PlatformEventChannel?

No. In API version 47.0 and later, the standard ChangeEvents channel cannot be retrieved, deployed, or deleted as a PlatformEventChannel. Instead, retrieve and deploy its member objects using PlatformEventChannelMember.