A subscription in OneSignal represents an email address, phone number, or device through which a user can receive push notifications and/or in-app message. There are four kinds 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. 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 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 Mobile Subscription ID will always be associated with the device in which it was created. However, new additional Subscriptions can be created for the same device if the user uninstalls and re-installs the app.

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.

Handling unsubscribed or invalid push tokens

When users uninstall your mobile app or their push token expires or they unsubscribe in the app's notification settings and never open the app again, they will not be able to receive push notifications. OneSignal detects this subscription status change when sending notifications. You can track these changes with both Event Streams and in the Push message reports Audience Activity, where unsubscribed subscriptions will appear.

If the user subscribes or unsubscribes in your app's notification settings and opens the app, our SDK's subscription change event listener can be used to detect these events.

Importing Mobile Subscriptions

Push tokens generated outside of OneSignal's SDK can be imported using our 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.

Migration from another push provider

If you are migrating from another push provider, this is the recommended sequence to ensure the best transition:

1. Follow our Mobile SDK setup to add OneSignal to your app and remove the other push provider's SDK.
2. Optional: Export user data including push tokens from your previous provider, then use our Create user API to add the user, External ID, and subscription properties. Avoid importing tokens for devices that have been inactive for several months.
3. Test the 2 scenarios (importing vs not importing)
   1. If you imported users via our API:
      1. iOS: Subscriptions can start receiving push notifications immediately. However, features like notification click tracking and confirmed deliveries require the OneSignal SDK to be active on the device.
      2. Android: Subscriptions will only receive push notifications if they have the OneSignal SDK active on the device, either through an auto-update or manual update. If they do not update, notifications will not be received until they install a version containing the OneSignal SDK.
   2. Update the app. You should not receive a new push permission prompt if the device was already subscribed to push.
4. Release the app with the OneSignal SDK.
   1. Users that auto-update will continue to receive notifications as usual if you imported them.
   2. Users that have not updated will need to be "nudged" to update.
5. Continue sending notifications from the previous push provider for a couple days, and send additional alerts asking them to update the app to the latest version. Then continue with OneSignal only.
6. Check the Confirmed Delivery. Any users that are not getting confirmed notifications either have not updated yet or the device is not connected to the internet, or it was an invalid push token (which should be marked as unsubscribed after a couple sends).

---

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.