Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

Frequency capping limits how many push notifications a single user can receive in a rolling time window (per minute, hour, day, or week). Use it to prevent over-messaging when multiple teams, Journeys, or automated triggers send to the same user.
Frequency capping is available on select paid plans.

​
How frequency capping works

Each delivered push “ages out” of the user’s rolling window when the configured time period has elapsed since that push was sent. Once the user has received the maximum number of notifications inside the window, OneSignal drops any additional sends until older notifications age out. Example: Frequency cap of 3 notifications per 24 hours.
TimeActionNotifications in windowDelivered?
Day 1, 9:00 AMSend Notification 11Yes
Day 1, 1:00 PMSend Notification 22Yes
Day 1, 5:00 PMSend Notification 33Yes
Day 2, 8:00 AMSend Notification 43 (cap reached)No
Day 2, 9:00 AMNotification 1 ages out (24h elapsed)2—
Day 2, 9:01 AMSend Notification 53Yes
Day 2, 10:00 AMSend Notification 63 (cap reached)No
Day 2, 11:00 AMSend Notification 73 (cap reached)No
Day 2, 1:00 PMNotification 2 ages out (24h elapsed)2—
Day 2, 2:00 PMSend Notification 83Yes
Notifications 4, 6, and 7 are dropped because the user’s rolling 24-hour window already holds three notifications at the moment each is sent.
“Per day” refers to a rolling 24-hour window, not a calendar day. If a user receives a message at 6:45 PM, that notification stays in their window until 6:45 PM the next day. Sends in that interval count toward the cap and may be dropped.

​
When to use frequency capping

Frequency capping is most useful when messaging volume can grow without coordination:
  • Complex campaign environments — large organizations with multiple teams or overlapping marketing campaigns.
  • High-frequency triggers — systems that send notifications from frequent events (stock price updates, automated news alerts, etc.).

​
What gets capped

  • Frequency capping applies to push notifications only. It does not apply to email, SMS, or in-app messages.
  • It applies to all push sources — Create notification API, Journeys, and manual dashboard sends.
  • Messages blocked by the cap are dropped, not queued. They are never retried.
For example, with a cap of 2 per day, if a user has already received two API pushes, a Journey push later that day is dropped unless the sender explicitly overrides the cap (see Override frequency capping).

​
How to enable frequency capping

Configure frequency capping at the app level from the OneSignal dashboard.
1
Navigate to Settings > Push & In-app > Frequency Capping.
2
Set the maximum number of messages a user can receive in your chosen time window (per minute, hour, day, or week).
Frequency capping settings in the OneSignal dashboard, with fields for maximum messages and a selectable time window.

​
Override frequency capping

Override frequency capping on a per-message basis when a send must reach the user even if the cap is reached.
In the message’s Delivery Schedule, select Override frequency capping settings.
Delivery Schedule section of the push composer with the 'Override frequency capping settings' option selected.

​
Notes on overriding

  • Frequency capping must be enabled in the dashboard for this override to have any effect.
  • Overridden messages still count toward the cap, so they affect whether future messages are delivered to the same user.

​
Reporting

When frequency capping is enabled, you can monitor its impact in two places:
  • Dashboard message reports — each message’s delivery stats show the number of users skipped because of the cap.
  • View message API — returns the same per-message capped and overridden counts.
Each message has one of two related statuses:
  • Capped — frequency capping was applied; the response includes the number of users skipped.
  • Overridden — frequency capping is enabled for the app but was overridden for this message.

​
FAQ

​
What time windows are supported?

Per minute, per hour, per day (rolling 24 hours), and per week (rolling 7 days). All windows are rolling — they don’t reset on calendar boundaries.

​
Does frequency capping apply to email, SMS, or in-app messages?

No. The cap configured under Settings > Push & In-app > Frequency Capping only limits push notifications. Email, SMS, and in-app messages have their own delivery controls and aren’t affected.

​
What happens to messages that exceed the cap?

They are dropped, not queued. A push that would put the user past the cap is silently skipped for that subscription and never retried.

​
Do overridden messages count toward future caps?

Yes. Setting enable_frequency_cap to false (or selecting the dashboard override) lets that message reach the user, but it still counts in the rolling window and can push later messages past the cap.

​
Why is the parameter named enable_frequency_cap if I set it to false to deliver?

The parameter controls whether the cap applies to the message. Setting it to false means “do not apply the cap to this message” — the cap is disabled for that one send. The user-level cap configured in the dashboard remains active for every other send.

​
Where can I see how many sends were capped?

In any message’s delivery report (dashboard) or in the View message API response. Both surface the same per-message Capped and Overridden totals.

Throttling

Smooth out the rate at which notifications go out across your audience — separate from per-user capping.

Journeys overview

Multi-step automated messaging. Journey sends respect frequency capping unless they explicitly override it.

Create push notification

REST API for sending pushes. Set enable_frequency_cap to false to override the cap per message.

View message

Retrieve per-message stats, including the number of users capped or overridden.