Change Data Capture Allocations

• The event delivery allocation is how many event messages can be delivered in a 24-hour period to Pub/Sub API and CometD subscribers, empApi Lightning components, and event relays. It excludes non-API subscribers, such as Apex triggers, flows, and Process Builder processes. Published event messages that are delivered to non-API subscribers, such as Apex triggers, flows, and Process Builder processes, don’t count against the delivery allocation.
• The event delivery allocation is shared between high-volume platform events and Change Data Capture events.

Event Delivery Usage Combined for All Subscribers

The number of delivered events to clients is counted for each subscribed client, including event relays. If you have multiple client subscribers, your usage is added across all subscribers. For example, you have an Unlimited Edition org with a default allocation of 50,000 events in a 24-hour period. Within a few hours, 20,000 event messages are delivered to two subscribed clients. So you consumed 40,000 events and are still entitled to 10,000 events within the 24-hour period.

How Is Event Delivery Usage Calculated?

The daily event delivery limit is a rolling limit. It’s calculated for the number of delivered events in the last 24 hours. As time goes by, the usage is updated. The event delivery limit is checked when a new event is received.

To learn more about how event usage is calculated against your event allocations, see Learn About Daily Rate Limits in the App Development Without Limits Trailhead module.

How to Avoid Exceeding Event Allocations

Proactively monitor your event usage. For more information, see Monitor Event Usage Against Your Allocations and Enhanced Usage Metrics in the Platform Events Developer Guide. When your event delivery usage gets close to the allocation, try these methods to reduce the consumption of delivered events.

• Use stream filtering to reduce the amount of events delivered to the subscriber and receive only relevant events. For more information, see Filter Your Stream of Change Events with Channels.
• Use custom channels instead of the default ChangeEvents channel to only receive the events related to the entities you’re interested in. See Compose Streams of Change Data Capture Notifications with Custom Channels.
• Make sure you don’t have unnecessary subscribers. Each event delivered to a subscriber counts against the event delivery allocation.

What to Do If You Exceed the Event Delivery Allocation

If you exceed the default event delivery allocation, an error is returned and the subscription is disconnected.

• The error you receive in a CometD client is: 403::Organization total events daily limit exceeded. The error is returned in the Bayeux /meta/connect channel when a CometD subscriber first connects or in an existing subscriber connection. For more information, see Streaming API Error Codes in the Streaming API Developer Guide.
• The error code that you receive in a Pub/Sub API client is: sfdc.platform.eventbus.grpc.subscription.limit.exceeded. And the error message is: You have exceeded the event delivery limit for your org.

When the client reaches the event delivery allocation, perform one of these steps.

• Keep the subscriber disconnected for a temporary time. While the subscriber is disconnected, the event usage for the last 24 hours decreases after some time. The events received in Salesforce during the disconnected state are stored for the retention period of 72 hours. After usage decreases, resume the subscription from where it left off and receive events. You can retrieve stored event messages with Pub/Sub API and CometD using the Replay ID.
• If you reach the event delivery limit often and your event volume is high, consider purchasing an add-on to increase your event allocations by contacting your Salesforce Account Representative. See Which Allocations Can Be Increased?.

Which Allocations Can Be Increased?

You can increase the event delivery allocation and remove the limit on the maximum number of entities selected for change notifications. To do so, purchase a Change Data Capture add-on by contacting your Salesforce Account Representative. The add-on moves your event delivery usage to a monthly entitlement model and allows for spikes in usage. See Increase Your Event Delivery Allocation with an Add-On License.

To verify the current usage of selected entities, perform this Tooling API query through REST or in the Developer Console Query Editor.

SELECT COUNT_DISTINCT(SelectedEntity) FROM PlatformEventChannelMember

The query gets the number of unique entities selected across all channels. The query can return a number higher than the selected entities allocation if entity selections are made by AppExchange packages. The latter selections aren’t counted against the selected entities allocation.

The SelectedEntity field of PlatformEventChannelMember in Metadata API and Tooling API represents the entities selected through the user interface or the API. For more information, see Select Objects for Change Notifications with Metadata API and Tooling API.

For more information about the Tooling API query REST resource, see REST Resources in the Tooling API Developer Guide.

If you install an AppExchange released managed package, the selections made by the AppExchange package in a custom channel don’t count against your org’s allocation. You can install the AppExchange package even if the org reaches the maximum number of selected entities default allocation. Also, installing the AppExchange package doesn’t alter the current usage for the number of selected entities. This statement holds true for first- and second-generation packages. For package developers, the entity selection allocation is still enforced in the package development org.

Check out the benefits and facts about an add-on license.

• The add-on increases the 24-hour allocation of delivered event messages by 100,000 per day (3 million a month) as a usage-based entitlement.
• The add-on removes the limit on the maximum number of entities selected for change notifications.
• The daily delivery usage isn’t as strictly enforced as the default allocation. The add-on allows for spikes in usage through a grace allocation. The grace allocation is higher than the allocation that you purchased through the add-on license. As long as the daily event delivery usage is within the grace allocation, your subscribers aren’t stopped and can continue receiving events. Salesforce reserves the right to adjust grace allocations at any time.
• The entitlement is reset every month after your contract start date.
• Entitlement usage is computed only for production orgs. It isn’t available in sandbox or trial orgs. For more information, see Usage-based Entitlement Fields.
• Salesforce monitors event overages based on a calendar month, starting with your contract start date. If you exceed the monthly entitlement, Salesforce contacts you to discuss your event usage needs. The entitlement used for monitoring monthly event overages is the daily allocation multiplied by 30.

To increase the entitlement for event delivery, contact your Salesforce Account Representative to purchase the add-on for additional change events.

Monitor Hourly Event Usage

To monitor event delivery usage by the hour, retrieve the daily event delivery usage using REST API every hour. For more information, see Monitor Hourly Event Delivery Usage with REST API in the Platform Events Developer Guide.

Track Event Usage Trends with SOQL Queries by Using PlatformEventUsageMetric

Perform a SOQL query on PlatformEventUsageMetric to get visibility into your event usage and usage trends. With enhanced usage metrics, you can view separate and combined metrics for platform events and change data capture events. Break down usage metrics by event name, client ID, event type, and usage type, and get usage data by granular time segments. PlatformEventUsageMetric data is available for CometD and Pub/Sub API clients, empApi Lightning components, and event relays. For more information, see Enhanced Usage Metrics in the Platform Events Developer Guide.