PlatformEventSubscriberConfig Metadata Type in SFDX

Why Every Platform Event Apex Trigger Needs a PlatformEventSubscriberConfig#

When you write an ApexTrigger on a Platform Event (Order_Status_Event__e), two default platform behaviors catch even experienced developers off guard:

1. Default Batch Size Is 2,000 (Not 200!): Under high event load, Salesforce passes up to 2,000 event messages into a single trigger invocation. If each event inserts or updates SObject records that fire downstream triggers and Flows, your transaction will immediately hit the 10,000-row DML limit or 10-second CPU timeout.
2. Default Running User Is Automated Process: The system Automated Process user cannot send emails via Messaging.sendEmail(), cannot access user-licensed managed packages, and complicates debug log capture.

PlatformEventSubscriberConfig (PlatformEventSubscriberConfigs/<Name>.platformEventSubscriberConfig-meta.xml) solves both issues declaratively—and starting in API v62.0, also unlocks Parallel Subscriptions (numPartitions) for up to 10x horizontal throughput!

Key Metadata Fields on PlatformEventSubscriberConfig#

Real-World XML Example (PlatformEventSubscriberConfigs/OrderEventTriggerConfig.platformEventSubscriberConfig-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<PlatformEventSubscriberConfig xmlns="http://soap.sforce.com/2006/04/metadata">
    <batchSize>200</batchSize>
    <isProtected>false</isProtected>
    <masterLabel>OrderEventTriggerConfig</masterLabel>
    <numPartitions>4</numPartitions>
    <partitionKey>Order_Event__e.External_Account_ID__c</partitionKey>
    <platformEventConsumer>OrderEventTrigger</platformEventConsumer>
    <user>integration.bot@acme.example.com</user>
</PlatformEventSubscriberConfig>

Querying PlatformEventSubscriberConfig and EventBusSubscriber#

1. Monitor Live Trigger Replay Positions and Errors in SOQL (EventBusSubscriber)#

SELECT ExternalId, Name, Topic, Type, Status, Position, Tip, Retries, LastError
FROM EventBusSubscriber
WHERE Type = 'ApexTrigger'
ORDER BY Topic ASC

2. Audit Configured batchSize and Running Users via Tooling API#

SELECT Id, DeveloperName, MasterLabel, BatchSize, NumPartitions, PartitionKey, UserId
FROM PlatformEventSubscriberConfig

Senior Architect Best Practices & Gotchas#

Frequently asked questions

Why is the default batchSize of 2,000 dangerous for Platform Event Apex triggers?

Unlike standard SObject triggers (which run in chunks of 200 records), Platform Event Apex triggers receive up to 2,000 events in one execution! If your trigger updates SObjects or runs SOQL, a 2,000-event batch can breach CPU or DML limits unless lowered via PlatformEventSubscriberConfig.

Why should you override the default Automated Process running user on a Platform Event trigger?

By default, Platform Event triggers run as Automated Process, which cannot send outbound emails, may lack access to installed package licenses or sharing rules, and sets CreatedById to Automated Process. Setting the user field runs the trigger as a dedicated integration User.

What do numPartitions and partitionKey do on PlatformEventSubscriberConfig?

Introduced in API v62.0, numPartitions (1 to 10) creates parallel internal subscriptions for a high-volume Platform Event Apex trigger, routing events across concurrent threads by hashing the specified partitionKey (such as EventUuid or a custom field).

How do you monitor Platform Event trigger subscriptions and replay IDs in SOQL?

You can query the EventBusSubscriber standard object in SOQL to inspect Name, Topic, Type, Position, Tip, Retries, LastError, and Status for every active Platform Event trigger.