Overview
In OneSignal, a User represents an individual with one or more Subscriptions across your messaging channels (mobile push, web push, email, and SMS).- Each User can have up to 20 Subscriptions.
- Every User is automatically assigned a OneSignal ID (UUID v4).
- Users start as anonymous until you assign them an External ID. Assigning an External ID links Subscriptions together and may replace the existing OneSignal ID if the user already exists in your app.
- Users and Subscriptions have different properties. For example, Tags are stored at the User level, while subscription status (opted-in/out) belongs to the Subscription.
- When the User context changes — for example, logging in (anonymous → identified) or switching accounts (UserA → UserB) — the Subscription is reassigned from the old User to the new one.
- The Subscription will now inherit the properties of the new User.
- Properties tied to the previous User (like Tags, language, or External ID) will no longer apply.
- UserA has Tag
premium=true - UserB has Tag
premium=false - If a Subscription moves from UserA to UserB, it will no longer be associated with
premium=trueand will instead reflect UserB’s properties.
Anonymous vs. identified users
- Anonymous user: Has no External ID → each Subscription is separate with its own OneSignal ID (treated as separate Users).
- Identified user: Has an External ID → OneSignal merges all Subscriptions under a single OneSignal ID.
- Web push Subscription →
OneSignal_ID_1 - Mobile Subscription →
OneSignal_ID_2 - Email Subscription →
OneSignal_ID_3 - SMS Subscription →
OneSignal_ID_4 - Result: Four Users (each Subscription is a separate User with unique properties)
- Web push Subscription with External ID
External_ID_A→OneSignal_ID_1 - Mobile Subscription with same
External_ID_A→ merged intoOneSignal_ID_1 - Email Subscription with same
External_ID_A→ merged intoOneSignal_ID_1 - SMS Subscription with same
External_ID_A→ merged intoOneSignal_ID_1 - Result: One User with four Subscriptions (all tied to the same User)
Always assign an External ID. This ensures Subscriptions across channels and devices unify under a single User profile and prevents duplication.
- Use stable, non-generic identifiers (e.g., your internal user ID or email address).
- Call
OneSignal.loginearly in your app lifecycle.
User properties
| Property | Description |
|---|---|
| External ID | A unique identifier you assign to unify the user with your system. |
| OneSignal ID | A UUID v4 auto-generated by OneSignal for each user. It may change upon assigning an External ID. |
| Aliases | Key-value pairs like mixpanel_id : 1234. See Aliases. |
| Channel | The Subscriptions the user has, such as Push, Email, or SMS. |
| Country | Country code in ISO 3166-1 Alpha-2 format. |
| Email from the most recent Email Subscription. | |
| First session | When the user was initially created in OneSignal. |
| IP Address | From the latest updated Subscription. |
| Language | User’s language in ISO 639-1 format. Can be updated via API or setLanguage. |
| Last session | The latest timestamp of app interaction. |
| Location | GPS coordinates of mobile subscriptions (if location tracking is enabled). See Location-Triggered Notifications. |
| Phone | Phone number from the most recent SMS Subscription. |
| Tags | Custom metadata (e.g. preferences, behavior). See Tags. |
| Test User name | A label assigned when marking a User as a test user. Set via the dashboard or the test_user_name property in the API. See Test Subscriptions. |
| Timezone | timezone_id in IANA TZ format, set by the SDK. Can be updated via API. |
OneSignal ID
The OneSignal ID is an internal UUID v4 generated to uniquely represent a user. It’s automatically created in scenarios such as:- First-time mobile app open (or after reinstall)
- New web push Subscription
- Creating Users/Subscriptions via Create user or CSV Import
- Clearing browser cache and returning to the site
- Logging out with
OneSignal.logout
OneSignal.login, any existing OneSignal ID tied to the current Subscription is replaced by the one associated with that External ID. Subscriptions across platforms (Push, Email, SMS) will be merged under the same OneSignal ID if they share the same External ID.
Reassignment and behavior
If a user reinstalls the app or clears cache, a new OneSignal ID and Subscription are created. However, callingOneSignal.login will link the new Subscription back to the original user profile.
Email and SMS Subscriptions added via OneSignal.User.addEmail or addSms inherit the current OneSignal ID. For full method details, see the Mobile SDK reference and Web SDK reference.
External ID
The External ID is a unique string you assign to users to track them across devices and Subscriptions.
OneSignal.login(recommended) — see Mobile SDK and Web SDK- Create user API
- Transfer subscription API
OneSignal.logout— removes the External ID and returns the User to anonymous
Restricted IDs
Do not use placeholder values or temporary values for External IDs. The following values cannot be used for External IDs:NANULL01-1nullUNQUALIFIEDallNaN00000000-0000-0000-0000-000000000000-noneok123ABCunknownINVALID_USERundefinednot set
Multiple users on the same device
When multiple users share a device, each new login should trigger a call toOneSignal.login with a different External ID. This reassigns the OneSignal ID and Subscription to the new user.
To handle logout, you can do the following to remove the user context:
- Call
OneSignal.logout()→ clears External ID, removes previous user properties (Tags, Aliases, etc.), and assigns anonymous OneSignal ID. - Optionally disable notifications using
optOut, and re-enable withoptInwhen logging back in.
Monthly active users (MAU)
MAU is used for billing and is defined as a mobile Subscription that has a last session within the 30-day billing period. This includes:- Users that open your app for the first time, creating a mobile Subscription via our SDK
- Users that reinstall the app and open it again, creating another mobile Subscription via our SDK
- Users that get imported via our API
MAU billing example
If a User has these Subscriptions:- iOS mobile (active in the last 30 days)
- Android mobile (active in the last 30 days)
- Web push
- SMS
Reducing MAUs (e.g., paywall use cases)
You can delay SDK initialization and Subscription creation using the mobile SDK privacy methods.- Call
setConsentRequired()before initializing the SDK — this prevents auto-creation of a Subscription - Call
setConsentGiven()when ready to create a Subscription for the user
FAQ
What happens when a user reinstalls the app?
A new OneSignal ID and Subscription are created. CallingOneSignal.login with the same External ID links the new Subscription back to the original User profile, preserving Tags, Aliases, and other User-level properties.
How many Subscriptions can a User have?
Each User can have up to 20 Subscriptions across all channels (mobile push, web push, email, and SMS).What is the difference between an anonymous and identified User?
An anonymous User has no External ID. Each Subscription is treated as a separate User with its own OneSignal ID. An identified User has an External ID, which causes OneSignal to merge all Subscriptions sharing that External ID under a single User profile.Does subscription status affect MAU billing?
No. Any mobile Subscription with a session in the 30-day billing period counts as an MAU, regardless of whether the Subscription is opted in or opted out of notifications.Related pages
Subscriptions
Devices, email addresses, and phone numbers that receive your messages.
Aliases
Map custom identifiers to Users for cross-platform tracking and integrations.
Tags
Set key-value data on Users for personalization and segmentation.
Identity verification
Require server-generated JWTs to prevent User impersonation.