A subscription record refers to the ways a user can receive messages sent from OneSignal. There are 3 types of subscriptions: push notifications, SMS, and email. In-app messages have the same subscription ID as mobile push as it is the same device.

As users subscribe to your messaging channels, they are assigned a Subscription ID to uniquely identify that specific channel. For instance, you cannot send push notifications to an email subscription or emails to an SMS subscription, etc.

Subscription properties

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

---

Create subscriptions

Subscriptions for each channel can be created through our SDKs, APIs, and in the case of email and SMS, using a CSV.

📘

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.

Create mobile push subscriptions

When the OneSignal SDK is initialized in your mobile app for the first time, it creates a subscription record for that user’s device. Users must then subscribe (aka “opt-in”) to receive push notifications for your app. See Prompt for Push Permissions for details.

If a user uninstalls and re-installs the app on the same device, this will create a new subscription ID for that same device. This is because the OneSignal SDK doesn’t track any Personally Identifiable Information and matches devices based on the push token. When a user uninstalls and re-installs the app on the same device, the push token changes, causing a new subscription to be created.

Import mobile push subscriptions

Mobile push subscription records 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 email addresses or phone numbers.

Before importing, we recommend releasing your app with the latest OneSignal SDK. 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.

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.

Create web push subscriptions

By initializing the OneSignal SDK on your website or progressive web app, you can prompt your users for push permissions. If a user accepts push notifications, a Subscription ID will be created with a unique push token. A separate web push subscription will be created for each browser and each browser profile where a user subscribes to your site.

When users clear their browser cache or cookies, this deletes the push subscription data from the browser and stops the user from receiving push notifications for that browser profile. If the user did not reset their push permissions for your site, they will be automatically and silently resubscribe to your site upon returning to it. However, this will generate a new subscription record.

Import 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.

Create email subscriptions

You can create new email subscription records using our SDK, REST API, or CSV importer.

To create a new email subscription using the SDK, you can call our addEmail SDK method. Doing so will add the email address as a new email subscription to the current user.

You can also call the Create subscription (by alias) REST API endpoint to add the subscription to an existing user, or create a new user for the subscription using the Create user endpoint.

Finally, you can import a list of emails using our CSV importer, which can either be associated with an existing user via an external ID or a new user will be created for the subscription.

Create SMS subscriptions

You can create new SMS subscription records using our SDK, our REST API, or our CSV importer.

Phone numbers must be in E.164 format to be valid.

To create a new SMS subscription using the SDK, you can call our addSMS SDK method. Doing so will add the phone number as a new SMS subscription to the current user.

You can also call the Create subscription (by alias) REST API endpoint to add the subscription to an existing user, or create a new user for the subscription using the Create user endpoint.

Finally, you can import a list of phone numbers using our CSV importer, which can either be associated with an existing user via an external ID or a new user will be created for the subscription.

---

Update & track subscriptions

Subscription data is automatically updated when users interact with our SDK in your app/website or sending messages. You can track this data via Event Webhooks, Exporting Data, and through our SDK.

Update & track mobile push subscriptions

Mobile Push Subscription properties get updated automatically when the user interacts with our SDK in your app. When the user has the app open, you can get the Subscription ID and track changes to the Mobile Push Subscription using the SDK Observer method.

If a user unsubscribes from push notifications, their subscription status will be updated when they open the app again. If the user does not open the app again, or uninstalls the app on the device, their subscription status will update when you send them notifications. See Notification Message Report for more details.

You can control the subscription status with the SDK optIn and optOut methods.

📘

Mobile push 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. If you are tracking users via the external ID, then it will associate both subscriptions with the same user.

Update & track web push subscriptions

Web Push Subscription properties get updated automatically when the user interacts with our SDK in your website. When the user has your site open, you can get the Subscription ID and track changes to the Web Push Subscription using the SDK Observer method.

If a user unsubscribes from push notifications, their subscription status will be updated when they return to the site in a new session. If the user does not return to the site, or clears browser data, their subscription status will update when you send them notifications. See Notification Message Report for more details.

You can control the subscription status with the SDK optIn and optOut methods.

📘

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 or subscribes on a different browser/browser profile. If you are tracking users via the external ID, then it will associate both subscriptions with the same user.

Update & track email subscriptions

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.

📘

Email Subscription ID persistence

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

Update & track SMS subscriptions

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

📘

SMS Subscription ID persistence

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

---

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.