A subscription represents a specific way a user can receive messages—like an email address, phone number, or device. There are four types of subscriptions:

• Email – for sending email messages
• SMS – for sending text messages
• Web Push – for sending push notifications to web browsers
• Mobile – for sending mobile push notifications, in-app messages, and Live Activities

Mobile subscriptions are unique because they’re tied to a specific device, allowing multiple message channels (push, in-app, Live Activities) to be delivered through the same subscription.

Users can have multiple subscriptions. For example, if someone subscribes to your website, installs your app on an Android device, and provides their email address, they’ll have three subscriptions: Web Push, Mobile (Android), and Email. If they later install your app on a new iPhone and provide a phone number, they'll now have five: Web Push, Mobile (Android), Email, Mobile (iOS), and SMS.

Each subscription has a unique Subscription ID, and messages can only be sent to matching subscription types. For instance, a push notification can't be sent to an Email subscription.

📘

Subscription limit per user

Each user can have a maximum of 20 Subscriptions. If a 21st Subscription is added, we will automatically remove the External ID from the oldest Subscription (based on last session) to stay within the limit. This oldest subscription will not be deleted, but will be assigned a new OneSignal ID and will therefore be classed as a separate user.

However, we will always ensure that you maintain at least 3 Email Subscriptions and 3 SMS Subscriptions if applicable.

See Users for details.

Subscription properties

Users can have multiple subscriptions, but each subscription will have the following properties.

---

Mobile subscriptions

Mobile Subscriptions are tied to a specific iOS, Android, Huawei, or Amazon device and support:

• Push notifications
• In-app messages
• Live Activities

A Mobile Subscription is automatically created when a user installs and opens your app with the OneSignal SDK.

If you're migrating from another provider, you can import existing push tokens using our Create user or Create subscription (by alias) APIs.

📘

Mobile subscription ID persistence

Each mobile subscription has a unique ID tied to the device it was created on.
If the app is uninstalled and reinstalled, a new subscription may be created.

To ensure all Subscriptions from the same user are linked, set the External ID using our SDK.

Keeping mobile subscription data up to date

Our SDK will automatically update mobile subscription properties based on user activity in your app. Additional features include:

• Prompt for push permissions and listen for permission (SDK) or subscription changes (SDK).
• Login the user (SDK) which sets the External ID and add custom Aliases.
• Add Tags with our addTag(s) methods (SDK).
• Update Language with our setLanguage method (SDK).

Handling uninstalls, unsubscribes, & invalid push tokens

Mobile subscriptions stop receiving push notifications, in-app messages, and Live Activities when:

• They uninstall the app.
• They disable push in the system settings and never open the app again.
• Their push token expires

OneSignal detects these changes automatically when sending messages. You can monitor unsubscribe events through:

• Event Streams
• Push message reports > Audience Activity

If a user unsubscribes or re-subscribes in system settings and then opens the app, use our SDK's subscription change event listener to detect the update in real time.

Migrating or importing mobile subscriptions

If you are switching to OneSignal from another push provider, see Migrating to OneSignal from another service.

---

Web push subscriptions

Web push subscriptions are tied to a specific device, browser, and browser profile. A user who subscribes on Chrome desktop will not receive push on Chrome mobile unless they also subscribe from that mobile device—creating a separate web push subscription.

New web push subscriptions are created in these scenarios:

1. User subscribes via your website by clicking “Allow” on the browser’s system-level permission prompt. This generates a unique push token and Subscription ID.
2. User clears browser data (history, cache, cookies, local storage) and revisits your site. This results in a new unique Subscription ID being created.

📘

Web push subscription ID persistence

Web push subscription IDs will never change. However, new subscription IDs will be created if the user clears browser data and returns to the site or subscribes on a different browser/browser profile.

To ensure all subscriptions from the same user are linked, set the External ID using our SDK.

Keeping web push subscription data up to date

Our SDK will automatically update web push subscription properties based on user activity on your site. Additional features include:

• Prompt for push permissions and listen for permission (SDK) or subscription changes (SDK).
• Login the user (SDK) which sets the External ID and add custom Aliases.
• Add Tags with our addTag(s) methods (SDK).
• Update Language with our setLanguage method (SDK).

Handling unsubscribes & invalid push tokens

Web push subscriptions stop receiving push notifications when:

• They clear browser data (history, cache, cookies, local storage).
• They disable push in the browser system settings.
• Their push token expires

OneSignal detects these changes automatically when sending messages. You can monitor unsubscribe events through:

• Event Streams
• Push message reports > Audience Activity

If a user clears browser data and returns to the site, their new web push subscription it will be subscribed to push, use our SDK's subscription change event listener to detect the update in real time and make sure to re-add the External ID with the login method.

Migrating or retaining web push subscriptions

Unlike mobile subscriptions, web push subscriptions cannot be manually imported due to browser security policies. However, if you're migrating from another provider, OneSignal can automatically take over existing subscriptions under specific conditions:

• You use an HTTPS site
• Your OneSignal setup uses the same origin (domain, subdomain, and protocol) as your previous provider

If these conditions are met, users who return to your site with the OneSignal SDK installed will be subscribed automatically without seeing another prompt. They'll also stop receiving messages from the previous provider.

When Users Need to Re-subscribe

If your setup does not match the original origin (e.g., switching between www.yoursite.com and your.com, or changing protocols http to https), browsers will treat your site as different. Users will need to manually resubscribe.

See Migrating to OneSignal from another service for more details.

---

Email Subscriptions

Email Subscriptions are based on the email address and can only receive emails.

Email Subscriptions can be created using:

1. The SDK addEmail method or Web Email Permission Prompt.
2. The Create user API or Create email API targeting the email address with include_email_tokens.
3. The Dashboard Email CSV Importer.

📘

Email Subscription ID persistence

Email addresses can only exist once per app. The Subscription ID for an email address is unique per app.

If the email address gets deleted and then added back to the same app, it will get a new Subscription ID.

Email Subscription properties get updated automatically when using the OneSignal SDK addEmail method. The subscription ID can be retrieved either by calling the View User API or by searching for the email address in the OneSignal dashboard under Audience > Subscriptions.

Users can be unsubscribed from email using any of the following methods:

• Unsubscribe links
• Custom unsubscribe pages
• Use the Update Subscription API
• Manually through the dashboard, by selecting “Unsubscribe from Emails” in the subscription’s options menu under Audience > Subscriptions

Resubscribing is possible through opt-in actions in the API or dashboard. This does not change the Subscription ID.

---

SMS subscriptions

SMS Subscriptions are based on the phone number in E.164 format and can only receive SMS and MMS. They cannot receive push notifications. The user's SMS app will display a notification when the SMS/MMS are received.

SMS Subscriptions can be created using:

1. The SDK addSms method or Web SMS Permission Prompt.
2. The Create user API or Create SMS API targeting the phone number with include_phone_numbers.
3. The Dashboard Phone Number CSV Importer.

📘

SMS Subscription ID persistence

Phone numbers can only exist once per app. The Subscription ID for a phone number is unique per app.

If the phone number gets deleted and then added back to the same app, it will get a new Subscription ID.

SMS Subscription properties get updated automatically when using the OneSignal SDK addSMS method. The subscription ID can be retrieved either by calling the View User API or by searching for the phone number in the OneSignal dashboard under Audience > Subscriptions.

Users can be unsubscribed from SMS using any of the following methods:

• Reply with "STOP" or similar keywords
• Use the Update Subscription API

---

Delete Subscriptions

The main reasons to delete subscriptions are for data privacy and removing inactive subscriptions. You can choose either to delete a single subscription or delete a user and all of its associated subscriptions. You can delete subscriptions in bulk if needed. See our guide to deleting users and subscriptions for more information.

📘

Automatic Subscription Deletion

Subscriptions that have a last session more than 18 months are deleted from our servers automatically for apps on free plans.

---

FAQ

What are the different subscription statuses?

Dashboard subscription statuses:

• Subscribed - the user should be able to receive messages on this channel.
• Unsubscribed - the user cannot receive messages on this channel. "User opted out" or "Manually unsubscribed"
• Never Subscribed - the user did not subscribe on this device. "Permission not granted" or "iOS Simulator unsupported"

API subscription status: invalid_identifier property set to true means unsubscribed and cannot get messages.

When do push subscription statuses get updated?

The subscription status will be updated in OneSignal automatically when the user:

1. Interacts with the OneSignal SDK. You can capture this event with our SDK Subscription Observer methods and send to your Database.

2. If the device token has been inactive for over 270 days, Google FCM will expire the token, and update the subscription record as unsubscribed.

3. After sending 2+ notifications to the unsubscribed device.

   1. Devices using FCM (Android Mobile Apps and Web) will alert OneSignal that the device is unsubscribed immediately after the 2nd notification is sent to the unsubscribed device.
   2. Devices using APNS (iOS devices like iPhone/iPad) will alert OneSignal that the device is unsubscribed after some time has passed between the first notification to the unsubscribed device and the 2nd notification sent.

Example sending 2+ notifications to detect unsubscribed devices:

• Notification 1 sent and user receives on device, then user unsubscribes.
• Notification 2 sent, the OneSignal Dashboard shows "Delivered" but the user does not actually receive it.
• Notification 3 sent, the OneSignal Dashboard shows Failed (Unsubscribed). On iOS, it may take additional notifications and time for the unsubscribed event to be sent to OneSignal from Apple.
• Notification 4 will not be sent to that device.

🚧

iOS Unsubscribe Detection

To protect user privacy, Apple doesn't want developers to know when a user removes the app. Some details provided by Apple can be found here: https://developer.apple.com/forums/thread/670868

If a device unsubscribes and opens the app, OneSignal detects this unsubscribe event right away and updates the record through our SDK. However if the device uninstalls the app or unsubscribes and does not open the app, it may take several weeks for Apple to report the unsubscribe event.

Apple will wait a random amount of time, typically over 14 days, before reporting a device is unsubscribed. The unsubscribed detection requires at least two notifications to be sent to the app, after the app is uninstalled.

Apple also has an edge case where development apps must have at least one currently installed in order to determine that another one is uninstalled and can't get notifications (in addition to the random multi-day delay involved). Details here: https://developer.apple.com/library/archive/technotes/tn2265/_index.html#//apple_ref/doc/uid/DTS40010376-CH1-TNTAG34

If you need to remove older devices, you can delete them using our dashboard or API.