Tags
Use OneSignal Data Tags to store user properties and track events for advanced segmentation and personalized messaging.
Data Tags are key-value pairs that let you store custom properties and track user behavior in OneSignal. They enable powerful segmentation, automation, and personalization.
Use tags to:
- Store user traits like
subscription_tierorname - Track behaviors like
purchases,clicks, orlevels - Segment users for messages and Journeys
- Personalize message content
Data tag value formatting rules
Important: All Tag values must be strings. You can still store numeric, timestamp, and boolean-like values—just stringify them.
| Value Type | Format Example | Notes |
|---|---|---|
| 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.
Recommended tag strategies
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.
Event-based behavior tags
Track user actions with tags. Great for triggering Journeys, follow-ups, or reminders.
| Key | Value Example | Description |
|---|---|---|
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.
| Key | Value Example | Description |
|---|---|---|
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.
| Key | Value Example | Description |
|---|---|---|
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.
| Key | Value Example | Description |
|---|---|---|
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.
| Key | Value Example | Description |
|---|---|---|
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 |
Ways 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
Importing and cleaning up Data Tags
Editing or deleting tags via CSV
- Export user data from the dashboard or API.
- Remove tag values by leaving cells blank.
- During CSV Import, enable:
- “Delete existing data tag values when the uploaded value is null”
- Save and upload your updated CSV.
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?
- Tags already set will persist.
- You can still read them.
- 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.
Example:
- 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
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.com
Please 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!
Tags
Use OneSignal Data Tags to store user properties and track events for advanced segmentation and personalized messaging.
Data Tags are key-value pairs that let you store custom properties and track user behavior in OneSignal. They enable powerful segmentation, automation, and personalization.
Use tags to:
- Store user traits like
subscription_tierorname - Track behaviors like
purchases,clicks, orlevels - Segment users for messages and Journeys
- Personalize message content
Data tag value formatting rules
Important: All Tag values must be strings. You can still store numeric, timestamp, and boolean-like values—just stringify them.
| Value Type | Format Example | Notes |
|---|---|---|
| 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.
Recommended tag strategies
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.
Event-based behavior tags
Track user actions with tags. Great for triggering Journeys, follow-ups, or reminders.
| Key | Value Example | Description |
|---|---|---|
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.
| Key | Value Example | Description |
|---|---|---|
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.
| Key | Value Example | Description |
|---|---|---|
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.
| Key | Value Example | Description |
|---|---|---|
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.
| Key | Value Example | Description |
|---|---|---|
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 |
Ways 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
Importing and cleaning up Data Tags
Editing or deleting tags via CSV
- Export user data from the dashboard or API.
- Remove tag values by leaving cells blank.
- During CSV Import, enable:
- “Delete existing data tag values when the uploaded value is null”
- Save and upload your updated CSV.
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?
- Tags already set will persist.
- You can still read them.
- 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.
Example:
- 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
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.com
Please 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!