Subscriptions

​

Overview

A Subscription represents a specific channel a user can receive messages through—such as an email address, phone number, or device. OneSignal supports four types of Subscriptions: Each user can have multiple Subscriptions. Use the External ID to identify the user across all Subscriptions. 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 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

Each Subscription has the following properties:

​

Subscription statuses

Generally, Subscriptions can either receive messages (Subscribed) or cannot (Unsubscribed). The details vary by channel:

---

​

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.

Notification Types definitions.

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.

0, -99 = Never Subscribed.

• The Subscription has not subscribed to the channel yet.

-2 = Unsubscribed.

• The Subscription cannot receive messages on this channel.
• Can be used with enabled property set to false if you are turning off messages on behalf of the user. Recommended value when turning off message permissions.
• Automatically set when the user unsubscribes.

-3, -5 = Android Support Library Error.Add or update your app’s Android Support Library.-4, -8, -11, -12 = Android Google Play Services Library Error.

• Check the logcat. See Getting a Debug Log.
• Upgrade your Google Play Services Library in your app and check the app’s logcat for Google Play Services errors. See Getting a Debug Log.

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

-13 = iOS missing_push_capability.

• Review the SDK setup docs to make sure all steps are implemented. See Channel setup.

-14, -16, -17 = iOS APNS Errors.

• The device is having an issue connecting to APNS. Check the Troubleshooting iOS guide and Getting a Debug Log.

-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, pushSubscriptionchange permission revoked-22 = Manually Unsubscribed via dashboard.

• Permission was revoked.

-23, -24 = Web Service Worker Error.

• See Web SDK troubleshooting.

-31 = Disabled via REST API.-98 = SMS Subscription awaiting double opt-in.

---

​

Mobile Subscriptions

Mobile Subscriptions represent iOS, Android, Huawei, or Amazon devices and support:

• Push notifications
• In-app messages
• Live Activities

They’re automatically created when a user installs and opens your app with the OneSignal SDK.

​

Updating mobile Subscriptions

Update Mobile Subscription properties using the OneSignal mobile SDK.

• Prompt for push permissions and observe permission/Subscription changes
• Login users to set External ID and Aliases
• Add Tags
• Set Language

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 below When do push Subscription statuses update? for more details.

• If the user re-installs the app on the same device or 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 a 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:

• Event Streams - detect unsubscribes when sending push
• Push reports - detect unsubscribes when sending push
• Use the SDK’s Subscription change listener - detect unsubscribes when user disables push in device settings then opens the app

---

​

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 to your website from that mobile device—creating a separate web push Subscription. 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.

​

Updating web push Subscriptions

Update web push Subscription properties using the OneSignal web SDK.

• Prompt for push permissions and observe permission/Subscription changes
• Login users to set External ID and Aliases
• Add Tags
• Set Language

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

Track changes via:

• Event Streams - detect unsubscribes when sending push
• Push reports - detect unsubscribes when sending push
• Use the SDK’s Subscription change listener - detect unsubscribes when user disables push then returns to the site

---

​

Email Subscriptions

Email Subscriptions are based on the email address and used only for email delivery. This is different from setting a Tag. 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

​

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 can become unsubscribed when:

• Sending emails, the user opts-out via the Unsubscribe link
• Setting enabled to false via the API
• Using the dashboard to unsubscribe the Subscription via the options button Email Subscriptions can become resubscribed via:
• Setting enabled to true via the API
• Using the dashboard to subscribe the Subscription 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

SMS Subscriptions are tied to E.164 formatted phone numbers (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

​

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 can 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 can 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

---

​

Importing or migrating Subscriptions

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

• Create user API
• Create Subscription API

---

​

Delete Subscriptions

Subscriptions can be deleted for:

• Data privacy
• Cleaning up inactive records

---

​

FAQ

​

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.

​

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 record (removes the channel entry but the user profile remains) and deleting the entire user profile (removes all subscriptions and user data). See 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.

---

​

Related pages