Tags

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 — stringify them before sending.

​

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

​

Tags vs Custom Events

Tags and Custom Events are both ways to add data to your users. However, there are some key differences: 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

---

​

Recommended tag strategies

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

​

Account status tags

Use these to target users by account tier or change in status.

​

Personalization tags

Use these for name-based message customization with Message personalization.

​

Location & demographic tags

Segment users by region or age.

​

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.

---

​

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)

​

Why are Tags not showing on a user?

Network connection — The most common cause. If the network is unstable or unavailable when the tag request fires, it may not reach the server.

• Mobile SDKs (v5+) cache tags locally and retry when a stable connection is detected.
• Web SDK requires the user to exist before tags can be set. The user is created when they subscribe to web push or you call addEmail/addSms. Calling the login method is recommended so the subscription is associated with a known user. Tags are sent automatically as long as the page session is still active — if the user navigates away before the tags are set, they are lost. Use getTags to verify, or call addTags again on the next session.

Browser cache cleared — When web subscribers clear their browser data, subscription data stored in the browser is destroyed. OneSignal can automatically resubscribe the user when they return, but tags are not restored unless:

1. The login method is called, which re-associates the new subscription with the existing user and their tags.
2. The tagging methods are called again on the new session.

​

Related pages