A Subscription in OneSignal represents the specific channel or device through which a user can receive messages. There are four types of Subscriptions: Email, SMS, Web Push, and Mobile. Mobile Subscriptions can receive push and in-app messages because they are tied to the same device.

Users can have multiple Subscriptions. For example, if a user subscribes to your website, downloads your mobile app on their Android device, then gives you their email address, this will be a total of 3 Subscriptions: Web Push, Mobile (Android), and Email. Later, this user gets a new iPhone and downloads your app, then provides you a phone number. This user now has 5 Subscriptions: Web Push, Mobile (Android), Email, Mobile (iOS), and SMS.

Subscriptions are identified by unique Subscription IDs. Messages can only be sent to the correct Subscription type. For example, a push notification cannot 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.

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 Android, iOS, Huawei, or Amazon device. They can receive both push notifications and in-app messages.

Mobile Subscriptions are created when a user installs and opens your app with the OneSignal SDK. If migrating to OneSignal from another provider, you can import push tokens and other data to create Subscriptions via our API. See below importing mobile subscriptions for details.

📘

Mobile Subscription ID persistence

The Subscription ID for a push token will never change. However, new Subscriptions will be created if the user uninstalls and re-installs the app on the same or different devices.

It is important to set the External ID to associate all Subscriptions with the same user.

Subscription properties get updated automatically when the user interacts with our SDK in your app. Use our SDK to:

• Prompt for push permissions and listen for permission or subscription changes .
• Login the user which sets the External ID.

Importing Mobile Subscriptions

Push tokens generated outside of OneSignal's SDK can be imported using the Create User API. You must have a valid push token for the device in order to successfully import them. You cannot send push notifications to invalid push tokens, email addresses or phone numbers.

Before importing, we recommend releasing your app with the latest OneSignal Mobile SDK setup. Any user that updates and opens the app with the OneSignal SDK will automatically be added to your OneSignal app and will keep their current subscription status (they will not be prompted if already granted push permissions).

Limitations with importing mobile Subscriptions:

iOS subscribers can be imported using our API and start getting push immediately. However, features like monitoring notification clicks and confirmed deliveries won't work for devices without the OneSignal SDK active.

Android subscribers can be imported using our API. Users that automatically updated the app will get push notifications, even if they don't open the app. However, anyone that doesn't automatically update the app will not be able to receive notifications until their device has a version of your app with the OneSignal SDK.

---

Web Push Subscriptions

Web Push Subscriptions can receive web push notifications and are tied to a unique device, browser, and browser profile. For example, users that subscribe on Chrome for desktop cannot also get push on Chrome for a mobile device unless they subscribe directly to your website on the mobile device. This generates 2 Web Push Subscriptions. Web Push Subscriptions cannot be imported into OneSignal. See below importing web push subscriptions for details.

Web Push Subscriptions are created in 2 ways:

1. When a user subscribes to push notifications through your website. They must click the "Allow" button on the browser's native Web permission prompts to get a push token and Subscription ID.
2. When a user clears their browser history, cache, cookies, local storage, and then returns to the site.
   1. This generates a new Subscription ID.

📘

Web Push Subscription ID persistence

The Subscription ID for a push token will never change. However, new Subscriptions will be created if the user clears browser data and returns to the site or subscribes on a different browser/browser profile.

It is important to set the External ID to associate all Subscriptions with the same user.

Subscription properties get updated automatically when the user interacts with our SDK in your app. Use our SDK to:

• Prompt for push permissions and listen for permission or subscription changes .
• Login the user which sets the External ID.

Importing Web Push Subscriptions

Due to the way browsers have set up web push, it’s industry standard that you cannot directly import subscriber data from a different push provider to a new provider. However, if your site meets the below requirements, current subscribers will be automatically moved into OneSignal when they return to the site. No prompt will be shown, and they can get push immediately after. They should also stop getting push from the previous provider.

1. Remove the previous web push SDK from your site. Only use the OneSignal Web Push SDK.
2. You must have an HTTPS website and use the same origin in which your users are currently subscribed.

If your site does not meet these requirements or you are changing your site origin (like removing/adding www), users will need to resubscribe to the site. You can continue to send push from the old provider until you are ready to fully move to OneSignal.

---

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.

How does subscription ID persistence work?

Mobile push subscriptions

A mobile push subscription for the same device can only be created if the user is uninstalling and re-installing the app on the same device, using multiple emulators for the same device, or if you are creating the subscription with our Create Subscription API.

The problem is there is not a simple method for tracking a specific device. We used to do this with the Google Advertising ID and Apple IdentifierForVendor, but due to the data privacy policy changes over the years, we stopped tracking this and only use push token because they are unique per device, but can change easily (like with uninstalling and re-installing the app or using emulators).

In the cases where the user is uninstalling and re-installing the app on the same device, this is very odd behavior and usually only something your developer or tester may be doing.

The push tokens for the older subscriptions will marked invalid as you send each subscription messages and FCM/APNS send us an invalid token response.

Web push subscriptions

Multiple web push subscriptions is common in cases where users clear their browser cache or site data. Upon returning to your site, a new subscription will be created for the browser/browser profile as the Subscription ID is stored in the IndexedDB (the user will not be asked to resubscribe however). Clearing notification permissions and then resubscribing will not change the subscription or subscription ID.

Email & SMS subscriptions

Each email address and phone number will have its own unique Subscription ID per App. The Subscription ID will never change unless the email address or phone number is deleted and added back to the app.