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 in web browsers
  • Mobile – for push, in-app messages, and Live Activities on mobile devices

Each user can have multiple subscriptions. For example, a user may have:

  • Web Push from subscribing on your site
  • Mobile (Android) after installing your app
  • Email after entering their address
  • Later, if they install your app on iOS and provide a phone number, they’ll have Mobile (iOS) and SMS, bringing the total to five subscriptions.

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.

Subscription properties

Each subscription has the following properties:

PropertyDescription
ChannelType of Subscription: Email, SMS, or Push. Push can be Mobile (iOS, Android, etc.) or Web. Only Mobile Push subscriptions support in-app messages.
Subscription StatusEither Subscribed or Unsubscribed. Unsubscribed status can have different subscription status definitions.
Last SessionDate/time of the last session with OneSignal SDK. For Email/SMS, it’s based on the most recent Push subscription.
Usage DurationTotal time (in seconds) the app or site was active with OneSignal SDK. Only tracked when session exceeds 60s.
SessionsCount of how many times the app/site was opened. A new session starts after 30+ seconds of inactivity.
First SessionTimestamp when the first Subscription for the User was created.
IP AddressNetwork location when using OneSignal SDKs. Not collected in the EU. See Handling Personal Data.
Subscription IDUUID representing the specific Subscription. Required for API messaging or updates.
OneSignal IDUUID representing the User. See Users.
External IDYour custom user ID. Helps link multiple subscriptions to the same user.
EmailOnly set for Email subscriptions.
Phone NumberOnly set for SMS subscriptions. Must be in E.164 format.
App VersionFrom SDK: Android versionCode, iOS CFBundleShortVersionString.
SDK VersionVersion of the OneSignal SDK used. See GitHub > SDKs (select your SDK) > Releases.
Timezone IDFrom the device at time of last interaction.
CountryDerived from IP address.
Location PointLatitude/longitude if location tracking is enabled. See Location-triggered notifications.
Language CodeFrom the device at time of subscription creation. See Multi-language messaging.
TagsCustom key-value metadata. See Tags.
Push TokenPlatform 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.
RootedIndicates 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.


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.

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.

Updating mobile subscriptions

Use the SDK to:

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:


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 from that mobile device—creating a separate web push subscription.

New web push subscriptions are created in these scenarios:

  • User subscribes via your website by clicking “Allow” on the browser’s system-level 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.

To ensure all subscriptions from the same user are linked, set the External ID using our SDK.

Updating web push subscriptions

Use the SDK to:

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:


Email subscriptions

Email subscriptions are based on the email address and used only for email delivery.

Created via:

  1. SDK addEmail or email prompt
  2. Create user or Create email API
  3. CSV Importer

Emails are unique per app. Deleting and re-adding the same email creates a new Subscription ID.

Manage email subscriptions

  • Use the dashboard, API, or Unsubscribe links
  • Resubscribe via SDK/API without changing Subscription ID

SMS subscriptions

SMS subscriptions are tied to E.164 formatted phone numbers.

Created via:

  1. SDK addSms or SMS prompt
  2. Create user or Create SMS API
  3. CSV Importer

Phone numbers are unique per app. Re-adding after deletion creates a new Subscription ID.

Manage SMS subscriptions

  • User replies with “STOP”
  • Update Subscription via API

Importing or migrating subscriptions

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

See Migrating to OneSignal for details.


Delete subscriptions

Subscriptions can be deleted for:

  • Data privacy
  • Cleaning up inactive records

See Delete users for details.

Subscriptions with no activity for 18+ months are automatically deleted on Free plans.


FAQ

What are the different subscription statuses?

Dashboard:

  • Subscribed – Active and messageable
  • Unsubscribed – Opted out or uninstalled the app
  • Never Subscribed – Never granted permission (unsubscribed)

API:

  • invalid_identifier: true means unsubscribed and cannot receive messages

When do push subscription statuses update?

Push subscriptions are updated:

  1. On interaction with 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 will be marked when you send it a notification.
  3. After sending 2+ notifications to the unsubscribed device.

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


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 in web browsers
  • Mobile – for push, in-app messages, and Live Activities on mobile devices

Each user can have multiple subscriptions. For example, a user may have:

  • Web Push from subscribing on your site
  • Mobile (Android) after installing your app
  • Email after entering their address
  • Later, if they install your app on iOS and provide a phone number, they’ll have Mobile (iOS) and SMS, bringing the total to five subscriptions.

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.

Subscription properties

Each subscription has the following properties:

PropertyDescription
ChannelType of Subscription: Email, SMS, or Push. Push can be Mobile (iOS, Android, etc.) or Web. Only Mobile Push subscriptions support in-app messages.
Subscription StatusEither Subscribed or Unsubscribed. Unsubscribed status can have different subscription status definitions.
Last SessionDate/time of the last session with OneSignal SDK. For Email/SMS, it’s based on the most recent Push subscription.
Usage DurationTotal time (in seconds) the app or site was active with OneSignal SDK. Only tracked when session exceeds 60s.
SessionsCount of how many times the app/site was opened. A new session starts after 30+ seconds of inactivity.
First SessionTimestamp when the first Subscription for the User was created.
IP AddressNetwork location when using OneSignal SDKs. Not collected in the EU. See Handling Personal Data.
Subscription IDUUID representing the specific Subscription. Required for API messaging or updates.
OneSignal IDUUID representing the User. See Users.
External IDYour custom user ID. Helps link multiple subscriptions to the same user.
EmailOnly set for Email subscriptions.
Phone NumberOnly set for SMS subscriptions. Must be in E.164 format.
App VersionFrom SDK: Android versionCode, iOS CFBundleShortVersionString.
SDK VersionVersion of the OneSignal SDK used. See GitHub > SDKs (select your SDK) > Releases.
Timezone IDFrom the device at time of last interaction.
CountryDerived from IP address.
Location PointLatitude/longitude if location tracking is enabled. See Location-triggered notifications.
Language CodeFrom the device at time of subscription creation. See Multi-language messaging.
TagsCustom key-value metadata. See Tags.
Push TokenPlatform 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.
RootedIndicates 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.


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.

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.

Updating mobile subscriptions

Use the SDK to:

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:


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 from that mobile device—creating a separate web push subscription.

New web push subscriptions are created in these scenarios:

  • User subscribes via your website by clicking “Allow” on the browser’s system-level 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.

To ensure all subscriptions from the same user are linked, set the External ID using our SDK.

Updating web push subscriptions

Use the SDK to:

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:


Email subscriptions

Email subscriptions are based on the email address and used only for email delivery.

Created via:

  1. SDK addEmail or email prompt
  2. Create user or Create email API
  3. CSV Importer

Emails are unique per app. Deleting and re-adding the same email creates a new Subscription ID.

Manage email subscriptions

  • Use the dashboard, API, or Unsubscribe links
  • Resubscribe via SDK/API without changing Subscription ID

SMS subscriptions

SMS subscriptions are tied to E.164 formatted phone numbers.

Created via:

  1. SDK addSms or SMS prompt
  2. Create user or Create SMS API
  3. CSV Importer

Phone numbers are unique per app. Re-adding after deletion creates a new Subscription ID.

Manage SMS subscriptions

  • User replies with “STOP”
  • Update Subscription via API

Importing or migrating subscriptions

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

See Migrating to OneSignal for details.


Delete subscriptions

Subscriptions can be deleted for:

  • Data privacy
  • Cleaning up inactive records

See Delete users for details.

Subscriptions with no activity for 18+ months are automatically deleted on Free plans.


FAQ

What are the different subscription statuses?

Dashboard:

  • Subscribed – Active and messageable
  • Unsubscribed – Opted out or uninstalled the app
  • Never Subscribed – Never granted permission (unsubscribed)

API:

  • invalid_identifier: true means unsubscribed and cannot receive messages

When do push subscription statuses update?

Push subscriptions are updated:

  1. On interaction with 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 will be marked when you send it a notification.
  3. After sending 2+ notifications to the unsubscribed device.

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