Data Tags are key-value pairs that let you store custom properties and track user behavior in OneSignal. They enable powerful segmentation and personalization. Use tags to:
  • Store user traits like subscription_tier or name
  • Track behaviors like purchases, clicks, or levels
  • Segment users for messages and Journeys
  • Personalize message content

​
Data tag value formatting rules

All Tag values must be strings. You can still store numbers, timestamps, and boolean-like values—just stringify them!
Value TypeFormat ExampleNotes
String Label"free", "VIP"For user types, privileges, statuses
Number"42", "3.14"Enables numeric filters (greater than, less than)
Timestamp"1685400000"Unix timestamp (in seconds). Use with Time Operators
Boolean"true" / "false", "1" / "0"Use "1"/"0" to reduce payload size
Not supported: Arrays, objects, nested values, or JSON blobs. If you need to store complex data, use Custom Events.

​
Restricted keywords

The following keywords are restricted and should not be used as tag keys because they are used internally for message personalization: message, notification, subscription, user, template, app, org, dynamic_content, data_feed, journey, custom_data See Message Personalization for more details.

​
Tags vs Custom Events

Tags and Custom Events are both ways to add data to your users. However, there are some key differences:
FeatureTagsCustom Events
Data usageSegmentation and personalizationTrigger Journeys without a Segment, Wait Until steps, personalization directly within Journeys
Data retentionLifetime30+ days (lifetime storage is available)
Data formatKey-value strings or numbersJSON
Data sourceOneSignal SDK, API, or integrations (limited)OneSignal SDK, API, or integrations
Data accessSegmentation and message personalizationJourneys and Journey-message-template personalization, Segmentation (Coming soon)
The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization. In practice, you will likely use both:
  • Tags for user properties that are static and don’t change often
  • Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows
Data Tags should represent information you want to use in messages or audience segmentation. They’re not meant to store full user profiles or logs—use your backend database for that. Tutorials:

Abandoned cart setup

Recover lost sales with abandoned cart reminders.

Abandoned cart dynamic content

Personalize your abandoned cart messages with dynamic content.

​
Event-based behavior tags

Track user actions with tags. Great for triggering Journeys, follow-ups, or reminders.
KeyValue ExampleDescription
cart_update"1685400000"Last time user added something to cart. Use Time Operators.
last_order"1684100000"Last completed purchase timestamp
amount_spent"100"Total spent—stringified number, no currency symbol
social_share"2"Count of social shares or referrals
tutorial_status"step2" or "completed"Tutorial progress—use readable or numbered string values

​
Game activity tags

Used by games to personalize based on user performance.
KeyValue ExampleDescription
points"1250"Experience or game points
level"8"Current game level
high_score"3000"Highest score achieved

​
Account status tags

Use these to target users by account tier or change in status.
KeyValue ExampleDescription
user_type"free", "premium"Subscription or access tier
has_downgraded"1" or "1685400000"Boolean or timestamp of downgrade
user_privileges"admin", "guest"Role-based segmentation
Use External ID to identify individual users. Do not use tags for this purpose. See External ID and Aliases.

​
Personalization tags

Great for name-based message customization using Variable Substitution.
KeyValue ExampleDescription
first_name"Jon"First name
last_name"Smith"Last name
user_name"PokeCatcher22"Display or screen name

​
Location & demographic tags

Segment users by region or age.
KeyValue ExampleDescription
region"New York"Metro area, optionally use ISO 3166-2
postcode"94105"Zip or postal code
location"Downtown LA"Custom string location
birthdate"915148800"Unix timestamp in seconds (birth date)
birth_year"1998"Four-digit birth year
age_range"18-35"Useful for general audience segmentation

​
How to add, update, and remove Tags

You can manage Tags using any of the methods below, depending on your use case and technical setup:

SDK Methods (Recommended)

Set tags in real time from your app or website as users perform actions.

REST API

Add, update, or remove tags server-side using our REST API.

Journeys

Automatically apply tags as users move through Journey steps.

CSV Import

Bulk update user tags by uploading a CSV with external_id or subscription_id.

Web Category Prompts

Prompt users to self-select interests, which are stored as tags.

In-App Messages

Collect or update tags based on in-app message click actions.

Manual Entry

Directly edit tags from the OneSignal Dashboard.
  • Go to Audience > Users > User Profile > Tags

Third-Party Integrations

Some integrations support syncing tags automatically.
  • Segment, HubSpot, Mixpanel, and others

​
FAQ

​
How many tags can I set per user?

Depends on your plan. See your plan limits or contact sales to increase your quota.

​
What happens to my tags if I exceed plan limits?

There is no limit to the number of tags available within a OneSignal app. The limit applies to how many tags can be set on each individual user at a single time. You can’t add or update tags for users who are at or above their limit. You must delete tags first, then send a second request to add new ones. Tags already set will persist. Example: Your plan limit = 20 tags/user.
  • User has 19 tags:
    • ✅ Add 1 new tag = success
    • ❌ Add 2+ new tags = failure
  • User has 20 tags:
    • ❌ Add any new tag = failure
    • ✅ Update 1+ existing tag = success

​
Where can I check tag usage?

  • Dashboard: Audience > Users > Tags column
  • Export users for a complete view

​
How do I reduce tag usage?

  • Remove tags using SDK or API
  • Use CSV Import to bulk delete
  • Use fewer, more reusable tags (e.g., status:active)
Need help?Chat with our Support team or email support@onesignal.comPlease include:
  • Details of the issue you’re experiencing and steps to reproduce if available
  • Your OneSignal App ID
  • The External ID or Subscription ID if applicable
  • The URL to the message you tested in the OneSignal Dashboard if applicable
  • Any relevant logs or error messages
We’re happy to help!