Skip to main content

​
Overview

Time Operators let you send messages relative to a specific moment in time—such as after an action happens or before an upcoming date. You store that moment as a Unix timestamp (in seconds) on the user using a Tag. OneSignal then compares the current time to that timestamp and lets you target users based on how much time has passed (or how much time remains). This makes it easy to automate messages like reminders, follow-ups, and deadlines without scheduling messages manually. Common use cases:
  • Abandoned cart: Remind users who haven’t checked out after a certain time
  • Event reminders: Message users before a scheduled appointment or renewal date
  • Milestones: Follow up when users haven’t completed an action by a deadline
  • Birthdays: Send automated messages on (or around) a user’s birthday
Time Operators are only available on paid plans. Free plans can still use default time-based segment filters like First Session and Last Session.

​
When should I use this?

Use Time Operators when you want to:
  • Send messages relative to an event, not at a fixed calendar time
  • Create moving time windows (for example, “24–48 hours after”)
  • Reuse the same logic for many users with different dates
  • Continuously evaluate eligibility as time passes
If you need to trigger messaging immediately when an event occurs, consider using Custom Events instead.

​
Tags vs Custom Events

You can solve many “reminder” use cases with either Tags or Custom Events. The best option depends on what you need to store and how you want to trigger automation.
  • Use Tags when you want to store the latest known timestamp on the user (for example, cart_updated_at or subscription_expires_at) and segment off that value over time.
  • Use Custom Events when you want to record each event occurrence (with properties) and trigger Journeys based on real-time behavior.
In practice, many implementations can use both: Custom Events for real-time tracking and Tags for user state you want to segment on later.
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

​
Quick reference

  1. Convert the event date into a Unix timestamp in seconds.
  2. Set a Tag where the key is the event name and the value is the timestamp as a string (e.g., 'event_date': '1739145600').
  3. Create a segment using the Time Elapsed Greater Than operator:
    • After a past date using Time Elapsed Greater Than operator with a positive value
    • Before a future date using Time Elapsed Greater Than operator with a negative value
A common mistake is setting timestamps in milliseconds (13 digits) instead of seconds (10 digits). Time Operators require seconds.

​
Send messages after a past event

Use this pattern when you want to message users after a certain amount of time has passed since something happened. Example: Abandoned cart reminder 24 hours after the user updated their cart
1

Store the timestamp when the event happens

When the user updates their cart, save the current time as a Unix timestamp (in seconds):
// SDK example
const timestampSeconds = String(Math.floor(Date.now() / 1000));
OneSignal.User.addTag("current_time", timestampSeconds);
Use seconds (10 digits), not milliseconds (13 digits).
2

Create a segment

  1. Go to Audience > Segments
  2. Add a User Tag filter
  3. Set Key to current_time
  4. Choose Time Elapsed Greater Than
  5. Set Value to 1 day (or 24 hours or 86400 seconds)
Segment using Time Elapsed Greater Than
3

Add an upper limit (Recommended)

Without an upper limit, users stay in the segment forever. Add a second filter to create a window:
  • Time Elapsed Greater Than 24 hours
  • Time Elapsed Less Than 48 hours
Now users are only in the segment between 24-48 hours after the event.
Segment with both Time Elapsed Greater Than and Less Than
4

Use the segment in a Journey

Create a Journey that targets your segment to automate the messaging.

​
Send messages before a future event

Use this pattern to message users leading up to a future date, such as an appointment or renewal.
  1. Store the future date as a Unix timestamp tag (e.g., 'future_date': '1739145600')
  2. Create a segment with Time Elapsed Greater Than and your desired entry time as a negative value
    • Example: -2 days (or -172800 seconds)
Segment using Time Elapsed Greater Than with a negative value
  1. Add an upper limit using the same Time Elapsed Greater Than operator with a negative value of a closer time
    • Example: -1 day (or -86400 seconds)
Segment using Time Elapsed Greater Than with a negative value and an upper limit

​
Example: Birthday messages

Send birthday messages by storing each user’s next upcoming birthday as a timestamp.
1

Store the next birthday timestamp

Calculate and store the user’s next upcoming birthday:
function getNextBirthday(month, day) {
  // month: 0-11 (Jan=0), day: 1-31
  const now = new Date();
  let birthday = new Date(now.getFullYear(), month, day);

  if (birthday <= now) {
    birthday = new Date(now.getFullYear() + 1, month, day);
  }

  return String(Math.floor(birthday.getTime() / 1000));
}

// Example: January 15th birthday
OneSignal.User.addTag("birthday", getNextBirthday(0, 15));
2

Create a birthday segment

  • User Tag: birthday
  • Time Elapsed Greater Than: 0 seconds
Users enter the segment once their birthday timestamp passes.
Birthday segment using Time Elapsed Greater Than 0
3

Set up a recurring Journey

  1. Create a Journey targeting your birthday segment
  2. Set re-entry to 52 weeks so users can re-enter next year
  3. Update the birthday tag to next year’s date after sending (in your backend or Journey)
Calculate birthday timestamps using the user’s local timezone when possible. Using server time only may cause messages to send earlier or later than expected.
If you want messages to stay accurate year-over-year, update the user’s birthday tag to the next upcoming birthday after you send the message (for example, in your backend or in a Journey step). Keep in mind, if you do this, it may be easier to use Custom Events instead.
Birthday messages will be sent to users around their birthday tag date.

​
FAQ

​
How does the math work? (technical details)

Time Operators exist to let you create relative, moving windows instead of fixed dates. OneSignal calculates elapsed time using this formula: 
time_elapsed = current_time - tag_timestamp
  • Past timestamps → positive values
  • Future timestamps → negative values
Operators:
  • Time Elapsed Greater Than X: matches when elapsed > X
  • Time Elapsed Less Than X: matches when elapsed < X
Why future timestamps match immediately with Less Than: Any negative number is less than any positive number. So time_elapsed_lt 2 days (172,800 seconds) will match a timestamp 30 days in the future because: 
-2,592,000 < 172,800  →  true (matches)
Because future timestamps always produce negative elapsed time, you must use negative values to define when users should enter and exit segments before an upcoming event. Positive values cannot represent time before a future date.

​
How can I test?

  1. Find your user via the External ID, Subscription ID, Email or Phone number. See Find and set test subscriptions for details on finding your user.
  2. Get a timestamp in seconds of the current date and a future date (5 minutes from now).
  3. Set two tags with the keys ‘current_time’ and ‘future_time’ and the values as the timestamps in seconds.
  4. Create a current_time segment with the following filters:
    • User Tag: current_time Time Elapsed Greater Than: 2 minutes
    • AND User Tag: current_time Time Elapsed Less Than: 5 minutes
  5. Create a future_time segment with the following filters:
    • User Tag: future_time Time Elapsed Greater Than: -5 minutes
    • AND User Tag: future_time Time Elapsed Less Than: -2 minutes
You should see your user:
  • Enter the current_time segment 2 minutes after the current time date and exit the segment 5 minutes after the current time date.
  • Enter the future_time segment 5 minutes before the future time date and exit the segment 2 minutes before the future time date.