Skip to main content

​
Overview

A Subscription is a single destination where a user can receive messages: an email address, a phone number, a web browser, or an app installed on a device. Each Subscription belongs to one user at a time and tracks its own subscription status. A user can have multiple Subscriptions (up to 20), including multiple of the same type. A phone and a tablet are two Mobile Subscriptions; a work and a personal email address are two Email Subscriptions. Use the External ID to link all of a user’s Subscriptions to the same user.
When a 21st Subscription is added, OneSignal removes the External ID from the oldest Subscription (based on last session) and assigns it a new OneSignal ID, effectively creating a new anonymous user for the inactive Subscription.However, OneSignal ensures at least 3 Email and 3 SMS Subscriptions (if applicable) are retained.See Users for details.
Each Subscription can receive messages from one or more channels: Most Subscription types carry a single channel. Mobile Subscriptions carry three, and each channel behaves independently. For example, a user who declines the push permission cannot receive push notifications, but their Mobile Subscription can still receive in-app messages. See Subscription statuses for details.
Subscriptions page showing Email, SMS, Web Push, and Mobile subscriptions linked by External ID

OneSignal Dashboard Audience > Subscriptions page. Shows multiple Subscriptions associated with a single user via the External ID.

In the image above, “userA” has 5 Subscriptions:
  1. Mobile (iOS) created after installing the iOS app. Call OneSignal.login to set the External ID and link the Subscription to the user.
  2. SMS created after the phone number was provided within the iOS app. See SMS Subscriptions below for details.
  3. Web Push created after subscribing to push on the website. Can receive web push notifications.
  4. Email created after the email address was provided. For sending email messages.
  5. Mobile (Android) created after installing the Android app. Can receive push notifications, in-app messages, and Live Activities.

​
Subscription properties

Properties that identify the Subscription and control delivery: Activity tracked on the Subscription: Properties shown alongside each Subscription that belong to the user, and are shared across all of the user’s Subscriptions:

​
Subscription statuses

A Subscription’s status answers one question: can this Subscription receive messages on a channel? Subscriptions that can are Subscribed; Subscriptions that cannot are either Unsubscribed (they opted out or lost a valid token) or Never Subscribed (they never opted in). The details vary by channel:
Status applies per channel, not to the Subscription as a whole. A Mobile Subscription’s status describes the push channel only: in-app messages are delivered whenever the user opens the app, regardless of push status, and Live Activities use their own per-activity tokens.
In the API, invalid_identifier: true means unsubscribed. Check notification_types for the specific reason.

​
notification_types

Indicates the Subscription’s ability to receive messages, including reasons for failures. Automatically updated via the frontend SDKs or manually via the API. Viewable via the View User API or Export CSV.
1 or positive number = Subscribed.
  • The Subscription can receive messages on this channel.
  • Can be used with enabled property if you are enabling messages on behalf of the user. For push Subscriptions, a valid token must still be set to receive push notifications. See our SDK setup docs for details.
In the API, values above 1 only occur on iOS. On all other channels (Android, Huawei, Amazon, Web, Email, SMS), a subscribed Subscription is set to 1; their failure states use the negative codes listed below.On iOS, a positive notification_types value is a bitmask of the notification authorization options the user has granted. Add the bit values below to interpret a specific number. Any positive value means the Subscription is Subscribed.For example, 47 = 32 + 8 + 4 + 2 + 1 = Provides App Notification Settings + CarPlay + Alert + Sound + Badge. Some values you may see:
  • 32 = Provides App Notification Settings
  • 43 = Provides App Notification Settings + CarPlay + Sound + Badge
  • 45 = Provides App Notification Settings + CarPlay + Alert + Badge
  • 47 = Provides App Notification Settings + CarPlay + Alert + Sound + Badge
  • 64 = Provisional
  • 80 = Provisional + Critical Alert
  • 88 = Provisional + Critical Alert + CarPlay
  • 91 = Provisional + Critical Alert + CarPlay + Sound + Badge
  • 160 = Announcement + Provides App Notification Settings
0, -99 = Never Subscribed.
  • The Subscription has not subscribed to the channel yet.
-2 = Unsubscribed (Opted Out).
  • Set when optOut() is called via the SDK, or when enabled is set to false via the API.
  • The Subscription cannot receive messages on this channel.
  • To re-enable, call optIn(). See optOut / optIn / optedIn (mobile | web) for details.
-3, -5 = Android Support Library Error.-4, -8, -11, -12, -29 = Android Google Play Services Library Error.-6 = Android Invalid Google Project Number.
  • The FCMv1 Sender ID doesn’t match the original in which this token belongs. Check the app’s logcat. See Getting a Debug Log.
-7, -9 = Android Outdated Google Play Services App.
  • Update or enable the Google Play Services app on the device.
-10 = Not Subscribed.
  • Push Subscription uninstalled app or unsubscribed in device settings.
  • Web push blocked notifications, cleared all data and workers.
-25, -26, -27, -28 = Huawei HMS PushKit Error.-13 = iOS missing_push_capability.
  • Review the SDK setup docs to make sure all steps are implemented. See Channel setup.
-14, -16, -17, -30 = iOS APNs Errors.-15 = iOS Simulator Error.
  • iOS Simulator requires iOS 16.4+. Use a different simulator or device.
-18 = Never Prompted.
  • The Subscription was never prompted to subscribe. This only tracks the required permission prompt and does not include in-app messages.
-19 = Prompted But Never Answered.
  • The Subscription was prompted but didn’t provide an answer.
-20, -21 = temp_web_record. Web push permission was revoked (pushsubscriptionchange).-22 = Manually Unsubscribed via dashboard.
  • Permission was revoked.
-23, -24 = Web Service Worker Error.-31 = Disabled via REST API.-98 = SMS Subscription awaiting double opt-in.

​
Mobile Subscriptions

A Mobile Subscription is your app installed on an iOS, Android, Huawei, or Amazon device. It is created automatically when a user installs and opens your app with the OneSignal SDK, and it can receive three channels:
  • Push notifications (requires push permission)
  • In-app messages (delivered when the user opens the app, no permission required)
  • Live Activities (iOS, requires the user to start an activity)
Each Mobile Subscription is tied to the device and push token it was created on. If your app is uninstalled and reinstalled on the same device, a new Subscription will be generated.Call OneSignal.login each time the user opens the app to make sure the External ID is set and the Subscription is linked to the user.

​
Updating mobile Subscriptions

Update Mobile Subscription properties using the OneSignal mobile SDK. You can update tags, language, and some other properties via the CSV Import feature. Mobile Subscriptions can be created and updated via the Users and Subscriptions APIs as well, but the mobile SDK is recommended for most use cases.

​
Handling uninstalls, unsubscribes, & invalid push tokens

Mobile Subscriptions stop receiving push notifications if the user:
  • Uninstalls the app
  • Disables push in device settings and never reopens the app
  • Push token expires
In these cases, the Subscription status will be set to Unsubscribed when sending push notifications. See When do push Subscription statuses update? for more details. Remember that an Unsubscribed Mobile Subscription can still receive in-app messages if the app is still installed.
  • If the user re-installs the app on the same device or a new device, a new Subscription will be created and they need to re-subscribe to receive messages.
  • If the user re-enables push in the device settings, the Subscription status will be set to Subscribed and the push token will be updated when they open the app.
  • If the push token expires, the Subscription status and new push token will update when the user opens the app on the same device.
Track changes via:

​
Web push Subscriptions

A Web Push Subscription is a specific browser profile on a specific device that has opted in to push from your website. 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. Two browsers on the same laptop are also separate Subscriptions. New Web Push Subscriptions are created in these scenarios:
  • User subscribes to your website by clicking “Allow” on the browser’s system-level native permission prompt. This generates a unique push token and Subscription ID.
  • 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 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.Call OneSignal.login each time the user opens the site or within the Subscription change listener to make sure the External ID is set and the Subscription is linked to the user.

​
Updating web push Subscriptions

Update Web Push Subscription properties using the OneSignal web SDK. You can update tags, language, and some other properties via the CSV Import feature. Web Push Subscriptions cannot be created via the REST API. You can update them with the Users and Subscriptions APIs, but the web SDK is recommended for most use cases.

​
Handling unsubscribes & invalid push tokens

Web Push Subscriptions stop receiving push notifications if the user:
  • Clears browser data (history, cache, cookies, local storage)
  • Disables push in the browser system settings
  • Push token expires
In these cases, the Subscription status will be set to Unsubscribed when sending push notifications. See When do push Subscription statuses update? for more details.
  • If the user returns to the site after clearing browser data, a new Subscription will be created and they will be automatically re-subscribed to receive messages if you have auto-resubscribe enabled.
  • If the user re-enables push in the browser settings, the Subscription status will be set to Subscribed when they return to the site.
  • If the push token expires, the Subscription status and new push token will update when the user returns to the site.
Chromium put out a blog post in October 2025, regarding a change that will automatically revoke push permissions for users with low site engagement who are being sent a high volume of notifications. The threshold for when a user is considered to have a low engagement score, appears to be about 30 days of inactivity. When revoked, the end user should receive a notification from Chrome directly.
Track changes via:

​
Email Subscriptions

An Email Subscription is a single email address used for email delivery. Storing an email address as a Subscription is different from setting it as a Tag: only a Subscription can receive messages. Create Email Subscriptions via:
  1. SDK addEmail method or email prompt - use these methods after calling OneSignal.login to set the External ID and link the Subscription to the user.
  2. Create user API or Create email API
  3. Dashboard CSV Importer or manually add email addresses
Emails are unique per app. Deleting and re-adding the same email creates a new Subscription ID.It is recommended to include the external_id when creating Email Subscriptions to link them to a User.

​
Managing email Subscriptions

Link to a user Make sure to set the external_id when creating Email Subscriptions to link them to a User.
  • Using the SDK, call the login method before calling addEmail to set the external_id and link the Email Subscription to the user.
  • Using the CSV Importer or REST API, set the external_id identifier with the email.
Subscription statuses Newly created Email Subscriptions will automatically be set to Subscribed unless otherwise specified. Email Subscriptions become unsubscribed when:
  • The user opts out via the unsubscribe link
  • You set enabled to false via the API
  • You unsubscribe the Subscription in the dashboard via the options button
Email Subscriptions become resubscribed when:
  • You set enabled to true via the API
  • You subscribe the Subscription in the dashboard via the options button
If a user unsubscribes from emails, you can keep them as unsubscribed but send them important emails by sending to unsubscribed emails.

​
SMS Subscriptions

An SMS Subscription is a single phone number in E.164 format (e.g., +14155551234). Create SMS Subscriptions via:
  1. SDK addSms method or SMS prompt - call OneSignal.login first to set the External ID and link the Subscription to the user.
  2. Create user or Create SMS API
  3. Dashboard CSV Importer
Phone numbers are unique per app. Re-adding after deletion creates a new Subscription ID.Include the external_id when creating SMS Subscriptions to link them to a User.

​
Managing SMS Subscriptions

Link to a user Set the external_id when creating SMS Subscriptions to link them to a User.
  • Using the SDK, call the login method before calling addSms to set the external_id and link the SMS Subscription to the user.
  • Using the CSV Importer or REST API, set the external_id identifier with the phone number.
Subscription statuses Newly created SMS Subscriptions are automatically set to Subscribed unless otherwise specified. SMS Subscriptions become unsubscribed when:
  • The user replies with “STOP” or another opt-out keyword
  • You set enabled to false via the API
  • You unsubscribe the Subscription in the dashboard via the options button
SMS Subscriptions become resubscribed when:
  • The user replies with “START” or another opt-in keyword
  • You set enabled to true via the API
  • You resubscribe the Subscription in the dashboard via the options button
Re-subscribing an SMS Subscription without the user’s consent violates carrier compliance rules (TCPA, CTIA) and can result in carrier filtering or account suspension.

​
Importing or migrating Subscriptions

Import push tokens, email addresses, and phone numbers from another provider using:

Migrating to OneSignal

Import push tokens, emails, and phone numbers from another provider.

​
Deleting Subscriptions

Subscriptions can be deleted for:
  • Data privacy
  • Cleaning up inactive records
Deleting a Subscription removes that destination only. The user and their other Subscriptions remain. See Delete users for the difference between deleting a Subscription and deleting an entire user.

Delete users

Remove Subscriptions and user data for privacy or cleanup.
Subscriptions with no activity for 18+ months are automatically deleted on Free plans.

​
Finding Subscriptions

The easiest way to find a Subscription is through the OneSignal dashboard. If you already know the user’s External ID, email, or phone number, search for it directly in Audience > Subscriptions.

​
Search by last active

If you don’t know the user’s ID, you can find your device by activity:
  1. Open your app or site on the device you want to find. Make sure OneSignal is initialized (code actively running).
  2. In the OneSignal dashboard, go to Audience > Subscriptions.
  3. Sort by Last Active (arrow pointing up) to see the most recently active devices at the top.

​
Verify it is your device

If multiple Subscriptions appear, use the Displayed Columns filter at the top-right to show additional columns that help identify your device:

​
Find by segment tag

If you added a specific tag to the user (e.g., user_name or another identifier), you can create a segment with the User Tag filter to isolate that device.
Segment builder with a user tag filter to find a specific device

​
Find Subscription ID programmatically

For developers who need the Subscription ID directly from code:
  1. Open your site in the browser profile that is subscribed to push.
  2. Open the browser console (F12 or right-click > Inspect > Console).
  3. Run: OneSignal.User.PushSubscription.id
  4. The Subscription ID is logged to the console.
For mobile web, connect your Android device via USB and use chrome://inspect/#devices to open a remote console session.
Use the OneSignal SDK User Data Methods to log the Subscription ID to the console from Xcode or Android Studio.

​
FAQ

​
Why can’t I find my Subscription in the dashboard?

The most common causes are:
  • The OneSignal SDK is not initialized on the page or screen you are using.
  • You are searching by the wrong ID type. Try searching by email, phone number, or Subscription ID instead.
  • The Subscription was created in a different OneSignal app (e.g., staging vs. production).

​
Why did my “unsubscribed” user receive an in-app message?

Subscription status applies per channel. A Mobile Subscription that is Unsubscribed from push can still receive in-app messages, because in-app delivery only requires the app to be installed and opened, not push permission. This is working as designed. See Subscription statuses.

​
When do push Subscription statuses update?

Push Subscription statuses update through two mechanisms: 1. When the user opens your app or site The OneSignal SDK checks whether the push token is valid and whether notification permissions are still granted, then updates the Subscription status immediately. For example, if a user disables push notifications in their device settings and then reopens your app, the SDK detects the change and marks the Subscription as Unsubscribed right away. You can capture these changes with the SDK’s Subscription Observer (mobile | web) to sync status to your own database. 2. When you send push notifications If a user uninstalls your app, clears browser data, or disables push and never returns, OneSignal cannot detect the change until you send a notification. The push service (FCM, APNs, HMS) reports the token as invalid, and OneSignal marks the Subscription as Unsubscribed. This detection typically takes 2 or more messages because the push service does not immediately reject an invalid token: Use Event Streams to detect unsubscribes in real time when sending messages.
If you go long periods without sending to all users, unsubscribes accumulate silently and appear as a large spike when you resume sending. Send to all users at least once or twice a month to detect unsubscribes gradually. See FCM expired token FAQ for more on unsubscribe spikes.
Apple delays unsubscribe reporting by 14+ days. To protect user privacy, Apple does not immediately report uninstalls or permission revocations. If a user opens your app after disabling push, OneSignal detects the change instantly via the SDK. If the user never opens the app again, it may take several weeks for Apple to report the invalid token after you send notifications.See Apple Forum and Technical Note for details. Use the dashboard or API to delete old subscriptions to keep your audience clean.

​
A Subscription was deleted and a new one was created. Why did the user’s data come back after they logged in?

When OneSignal.login is called with a user’s External ID, OneSignal links the new Subscription to their existing user profile. If a Subscription was deleted and a new one was created (for example, after a reinstall), calling login with the same External ID re-associates the new Subscription with the user’s profile. This is working as designed. Note that there is a difference between deleting a Subscription (removes that destination but the user profile remains) and deleting the entire user (removes all Subscriptions and user data). Deleting a Subscription keeps the user profile as long as the user has an External ID or alias. If a user has no External ID and no aliases, deleting their last Subscription also deletes the user profile automatically. See User lifecycle and Delete users for details.

​
If a user turns off notifications in their device settings and never opens the app again, what happens?

The Subscription remains marked as Subscribed in OneSignal until you send a notification to that device. After 2 or more send attempts, the push service reports the token as invalid and OneSignal marks the Subscription as Unsubscribed. See When do push Subscription statuses update? above for the full sequence.

Users

The OneSignal user model, aliases, and how users relate to Subscriptions.

Test users

Mark a User as a test user to validate message delivery before sending to production.

Delete users

Remove Subscriptions and user data for privacy or cleanup.

Migrating to OneSignal

Import push tokens, emails, and phone numbers from another provider.