​

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:

• Email – for sending email messages
• SMS – for sending text messages
• Web Push – for push notifications via web browsers
• Mobile – for push notifications, in-app messages, and Live Activities on mobile devices

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

---

​

Subscription properties

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	Indicates if the Subscription can receive messages. See Subscription status for more details.
Last Session	Timestamp of the last session tracked by the OneSignal SDK. For Email/SMS, it’s based on the most recent push Subscription.
Usage Duration	Total time (in seconds) the Subscription was active on the app or site tracked by the 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 being out-of-focus.
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. Used for identifying the Subscription.
OneSignal ID	UUID representing the User. See Users.
External ID	Your custom user ID. Helps link multiple Subscriptions to the same user.
Device	The device model the Subscription was created with. For example, armv81 for web push browsers are Android devices.
Email	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).

​

Subscription statuses

Generally, Subscriptions can either receive messages (Subscribed) or cannot receive messages (Unsubscribed). However, there are some exceptions: Mobile Subscriptions

• Subscribed: The user has granted permission to receive push notifications.
  • If you have iOS Provisional push enabled, then all iOS mobile Subscriptions are Subscribed until disabled by the user.
• Unsubscribed: The Subscription cannot receive push notifications but can receive in-app messages.
  • See Handling uninstalls, unsubscribes, & invalid push tokens for more details.
• Never Subscribed – User never granted permission (same as unsubscribed).

Web Subscriptions

• Subscribed: The user has granted permission to receive push notifications.
• Unsubscribed: The Subscription cannot receive push notifications.
  • See Handling unsubscribes & invalid push tokens below for more details.

Email Subscriptions

• Subscribed: The user should have provided consent to receive email messages and the email address is valid.
• Unsubscribed: The user opted-out of receiving emails but can be overridden if needed.
  • See Email Subscriptions below for more details.

SMS Subscriptions

• Subscribed: The user should have provided consent to receive SMS messages and the phone number is valid.
• Unsubscribed: The user opted-out of receiving SMS messages.
  • See SMS Subscriptions below for more details.

---

​

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.

---

​

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

Mobile Subscription properties are recommended to be updated via 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

Web push Subscription properties are recommended to be updated via 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 can’t be created via the REST API but can be updated with 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. Created via:

1. SDK addSms or SMS prompt - use these methods after calling OneSignal.login to set the External ID and link the Subscription to the user.
2. Create user or Create SMS API
3. CSV Importer

​

Manage SMS Subscriptions

• User unsubscribes by replying with “STOP” or other SMS consent keywords
  • The user can also resubscribe by replying with “START” or other SMS consent keywords
• Update Subscription via API enabled property

---

​

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

See Delete users for details.

---

​

FAQ

​

When do push Subscription statuses update?

Push Subscription statuses are updated:

1. When the user opens the app, the OneSignal SDK will check if the push token is valid and if notification permissions are granted, then update the Subscription status accordingly.

• You can capture this event with our SDK Subscription Observer methods and send to your Database.

2. After sending 2+ notifications to the Subscription. Use Event Streams to detect unsubscribes when sending messages.

Example:

• Message 1: Delivered. User receives on device, then user unsubscribes in device settings.
• Message 2: Delivered (but device doesn’t receive).
• Message 3: Fails (marked unsubscribed)
• Message 4: Not sent to the Subscription.

​

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

When users turn off notifications in the device settings they can no longer receive push notifications on that device. They will be marked as unsubscribed after sending notifications to the device. See When do push Subscription statuses update? for more details.

---