Understand and manage OneSignal subscriptions across channels like mobile push, web push, email, and SMS. Learn how subscriptions work, their properties, and how to update or migrate them.
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. For example, a user may have:
A user can have a maximum of 20 Subscriptions. If a 21st 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 user.
However, OneSignal ensures at least 3 Email and 3 SMS Subscriptions (if applicable) are retained.
See Users for details.
Each subscription has the following properties:
Property | Description |
---|---|
Channel | Type of Subscription: Email , SMS , or Push . Push can be Mobile (iOS, Android, etc.) or Web. Only Mobile Push subscriptions support in-app messages. |
Subscription Status | Either Subscribed or Unsubscribed . Unsubscribed status can have different subscription status definitions. |
Last Session | Date/time of the last session with OneSignal SDK. For Email/SMS, it’s based on the most recent Push subscription. |
Usage Duration | Total time (in seconds) the app or site was active with OneSignal SDK. Only tracked when session exceeds 60s. |
Sessions | Count of how many times the app/site was opened. A new session starts after 30+ seconds of inactivity. |
First Session | Timestamp when the first Subscription for the User was created. |
IP Address | Network location when using OneSignal SDKs. Not collected in the EU. See Handling Personal Data. |
Subscription ID | UUID representing the specific Subscription. Required for API messaging or updates. |
OneSignal ID | UUID representing the User. See Users. |
External ID | Your custom user ID. Helps link multiple subscriptions to the same user. |
Only set for Email subscriptions. | |
Phone Number | Only set for SMS subscriptions. Must be in E.164 format. |
App Version | From SDK: Android versionCode , iOS CFBundleShortVersionString . |
SDK Version | Version of the OneSignal SDK used. See GitHub > SDKs (select your SDK) > Releases. |
Timezone ID | From the device at time of last interaction. |
Country | Derived from IP address. |
Location Point | Latitude/longitude if location tracking is enabled. See Location-triggered notifications. |
Language Code | From the device at time of subscription creation. See Multi-language messaging. |
Tags | Custom key-value metadata. See Tags. |
Push Token | Platform token used for push delivery (e.g., APNS or FCM). Only for Push Subscriptions. - iOS Push APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). - Android Push FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore. |
Rooted | Indicates if the Android device is rooted (jailbroken). |
notification_types
Indicates the subscription’s ability to receive messages, including reasons for failures. Automatically updated via our frontend SDKs or manually via the API. Viewable via the View User API or Export CSV.
Notification Types definitions.
1
or positive number = Subscribed.
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.
-2
= Unsubscribed.
enabled
property set to false
if you are turning off messages on behalf of the user. Recommended value when turning off message permissions.-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
.
-6
= Android Invalid Google Project Number
.
token
belongs. Check the app’s logcat. See Getting a Debug Log.-7
, -9
= Android Outdated Google Play Services App
-10
= Not Subscribed.
-13
= iOS missing_push_capability
.
-14
, -16
, -17
= iOS APNS Errors
.
-15
= iOS Simulator Error
.
-18
= Never Prompted.
-19
= Prompted But Never Answered.
-20
, -21
= temp_web_record. Web, pushsubscriptionchange
permission revoked
-22
= Manually Unsubscribed via dashboard.
-23
, -24
= Web Service Worker Error
.
-31
= Disabled via REST API.
-98
= SMS Subscription awaiting double opt-in.
Mobile subscriptions represent iOS, Android, Huawei, or Amazon devices and support:
They’re automatically created when a user installs and opens your app with the OneSignal SDK.
Each mobile subscription is tied to the device & push token it was created on. If uninstalled/reinstalled, a new Subscription ID may be generated.
Link subscriptions to the same user by setting an External ID.
Use the SDK to:
Mobile subscriptions stop receiving push notifications if the user:
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.
Track changes via:
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 from that mobile device—creating a separate web push subscription.
New web push subscriptions are created in these scenarios:
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.
To ensure all subscriptions from the same user are linked, set the External ID using our SDK.
Use the SDK to:
Web push subscriptions stop receiving push notifications if the user:
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.
Track changes via:
Email subscriptions are based on the email address and used only for email delivery.
Created via:
addEmail
or email promptEmails are unique per app. Deleting and re-adding the same email creates a new Subscription ID.
SMS subscriptions are tied to E.164 formatted phone numbers.
Created via:
addSms
or SMS promptPhone numbers are unique per app. Re-adding after deletion creates a new Subscription ID.
Import push tokens, email addresses, and phone numbers from another provider using:
See Migrating to OneSignal for details.
Subscriptions can be deleted for:
See Delete users for details.
Subscriptions with no activity for 18+ months are automatically deleted on Free plans.
Dashboard:
API:
invalid_identifier: true
means unsubscribed and cannot receive messagesPush subscriptions are updated:
Example:
To protect user privacy, Apple introduced delays (usually 14+ days) before reporting unsubscribes/uninstalls. See Apple Forum and Technical Note for more.
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.
Use the dashboard or API to delete old subscriptions.
Understand and manage OneSignal subscriptions across channels like mobile push, web push, email, and SMS. Learn how subscriptions work, their properties, and how to update or migrate them.
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. For example, a user may have:
A user can have a maximum of 20 Subscriptions. If a 21st 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 user.
However, OneSignal ensures at least 3 Email and 3 SMS Subscriptions (if applicable) are retained.
See Users for details.
Each subscription has the following properties:
Property | Description |
---|---|
Channel | Type of Subscription: Email , SMS , or Push . Push can be Mobile (iOS, Android, etc.) or Web. Only Mobile Push subscriptions support in-app messages. |
Subscription Status | Either Subscribed or Unsubscribed . Unsubscribed status can have different subscription status definitions. |
Last Session | Date/time of the last session with OneSignal SDK. For Email/SMS, it’s based on the most recent Push subscription. |
Usage Duration | Total time (in seconds) the app or site was active with OneSignal SDK. Only tracked when session exceeds 60s. |
Sessions | Count of how many times the app/site was opened. A new session starts after 30+ seconds of inactivity. |
First Session | Timestamp when the first Subscription for the User was created. |
IP Address | Network location when using OneSignal SDKs. Not collected in the EU. See Handling Personal Data. |
Subscription ID | UUID representing the specific Subscription. Required for API messaging or updates. |
OneSignal ID | UUID representing the User. See Users. |
External ID | Your custom user ID. Helps link multiple subscriptions to the same user. |
Only set for Email subscriptions. | |
Phone Number | Only set for SMS subscriptions. Must be in E.164 format. |
App Version | From SDK: Android versionCode , iOS CFBundleShortVersionString . |
SDK Version | Version of the OneSignal SDK used. See GitHub > SDKs (select your SDK) > Releases. |
Timezone ID | From the device at time of last interaction. |
Country | Derived from IP address. |
Location Point | Latitude/longitude if location tracking is enabled. See Location-triggered notifications. |
Language Code | From the device at time of subscription creation. See Multi-language messaging. |
Tags | Custom key-value metadata. See Tags. |
Push Token | Platform token used for push delivery (e.g., APNS or FCM). Only for Push Subscriptions. - iOS Push APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). - Android Push FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore. |
Rooted | Indicates if the Android device is rooted (jailbroken). |
notification_types
Indicates the subscription’s ability to receive messages, including reasons for failures. Automatically updated via our frontend SDKs or manually via the API. Viewable via the View User API or Export CSV.
Notification Types definitions.
1
or positive number = Subscribed.
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.
-2
= Unsubscribed.
enabled
property set to false
if you are turning off messages on behalf of the user. Recommended value when turning off message permissions.-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
.
-6
= Android Invalid Google Project Number
.
token
belongs. Check the app’s logcat. See Getting a Debug Log.-7
, -9
= Android Outdated Google Play Services App
-10
= Not Subscribed.
-13
= iOS missing_push_capability
.
-14
, -16
, -17
= iOS APNS Errors
.
-15
= iOS Simulator Error
.
-18
= Never Prompted.
-19
= Prompted But Never Answered.
-20
, -21
= temp_web_record. Web, pushsubscriptionchange
permission revoked
-22
= Manually Unsubscribed via dashboard.
-23
, -24
= Web Service Worker Error
.
-31
= Disabled via REST API.
-98
= SMS Subscription awaiting double opt-in.
Mobile subscriptions represent iOS, Android, Huawei, or Amazon devices and support:
They’re automatically created when a user installs and opens your app with the OneSignal SDK.
Each mobile subscription is tied to the device & push token it was created on. If uninstalled/reinstalled, a new Subscription ID may be generated.
Link subscriptions to the same user by setting an External ID.
Use the SDK to:
Mobile subscriptions stop receiving push notifications if the user:
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.
Track changes via:
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 from that mobile device—creating a separate web push subscription.
New web push subscriptions are created in these scenarios:
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.
To ensure all subscriptions from the same user are linked, set the External ID using our SDK.
Use the SDK to:
Web push subscriptions stop receiving push notifications if the user:
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.
Track changes via:
Email subscriptions are based on the email address and used only for email delivery.
Created via:
addEmail
or email promptEmails are unique per app. Deleting and re-adding the same email creates a new Subscription ID.
SMS subscriptions are tied to E.164 formatted phone numbers.
Created via:
addSms
or SMS promptPhone numbers are unique per app. Re-adding after deletion creates a new Subscription ID.
Import push tokens, email addresses, and phone numbers from another provider using:
See Migrating to OneSignal for details.
Subscriptions can be deleted for:
See Delete users for details.
Subscriptions with no activity for 18+ months are automatically deleted on Free plans.
Dashboard:
API:
invalid_identifier: true
means unsubscribed and cannot receive messagesPush subscriptions are updated:
Example:
To protect user privacy, Apple introduced delays (usually 14+ days) before reporting unsubscribes/uninstalls. See Apple Forum and Technical Note for more.
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.
Use the dashboard or API to delete old subscriptions.