Articles in this section

See more

Using Relative Dates in Segments and Journeys

This document describes how to segment users or add filters to journeys based on date ranges relative to specific dates provided by campaign or journey-triggering events or API calls.

Data provided on triggering events or API calls can be used as inputs to dynamic lists or journey filters. For example:

  • A campaign might target a dynamic list that selects users whose favoriteColor is {{color}}. A triggering API call can then include a specific color.
  • A journey might filter out all users whose age is less than {{age}} . A triggering API call or event can then include a threshhold age.

In some cases, it's helpful to use this approach to segment or filter users based on a date range. For example:

Iterable uses a special syntax for specifying relative date ranges, as described below.

In this article

Specifying relative dates

To specify relative dates in segmentation or a journey filter, provide a start date followed by a date math expression. For example, now-10d:

Example relative date

  • The start date can be now or a Handlebars expression that references a date included on the triggering event or API call. When using a Handlebars expression, the start date should be separated from the date math expression by ||; for example, {{createdAt}}||+3d.

    In segmentation, now represents the time at the start of the current minute. In a journey filter tile, now represents the start of the minute during which Iterable processes the tile for a given user.

  • For a date math expression, use one or many instances of + and - followed by values to add or subtract; for example, {{createdAt}}||+1M-3d+2h.

    Date math expressions can include the following identifiers:

    • y - Years
    • M - Months
    • w - Weeks
    • d - Days
    • h or H - Hours
    • m - Minutes
    • s - Seconds

    NOTES

    • now is a UTC time
    • When adding or subtracting months or years, date math first modifies the month or year, then selects a day number that's as close as possible to the original day number. For example:
      • 2020-02-29 plus one year is 2021-02-28
      • 2020-03-31 minus one month is 2020-02-29
      • 2020-02-28 minus one month is 2020-01-28
      • 2020-02-29 minus one month is 2020-01-29
      • 2020-04-01 minus one month is 2020-03-01
      • 2020-05-01 minus one month is 2020-04-01

Rounding

Use an operator such as /d or /h to round a date down to the specified level of granularity. For example:

  • now/h - Rounds to the beginning of the current hour
  • {{upcomingEventDate}}||/y - Rounds to the beginning of the year represented by upcomingEventDate(a field on a triggering event or API call)

When rounding, use the identifiers described above.

Example relative date expressions

For the following examples, assume that the current time is 3:56 p.m. UTC:

  • now - the current time (3:56 p.m. UTC)
  • now-48h - 48 hours before the current time (3:56 p.m. UTC, two days ago)
  • now/d - Midnight 12am UTC at the start of the current day
  • now/h+1d - 3:00 p.m. UTC tomorrow
  • now/h+1M-5h - 10:00am UTC, one month from today
  • {{grandOpening}}||/h+3d - Three days after the top of the hour associated with grandOpening
  • {{cutoffDate}}||-1M - One month before cutoffDate

Specifying dates in API calls and events

For more information about how to specify dates and time zones in API calls and events, read Field Data Types.

Date comparisons and time zones

When comparing dates and times, Iterable takes time zones into account. For example, assume that:

  • A user profile has a date1 field set to 2020-03-01 14:00:00 -0400.
  • A journey-triggering API call provides a date2 value of 2020-03-01 18:00:00 +0000.

These values represent the same date, but in different time zones. Because of this, an Is Exactly comparison for these two dates (in an Iterable segmentation query or journey filter tile) will indicate that these two dates are the same.

Similarly, Iterable uses the same time zone when comparing now to another date.

Handlebars always references event or API data

When specifying relative dates in a segmentation query or a journey filter, Handlebars expressions always reference triggering event or API fields—not user profile fields. For example, in the following journey filter definition:

Example relative date Handlebars expression

  • Profile Updated Date, on the left-hand side of the query, references a user profile field.
  • {{signupDate}}, on the right-hand side of the query, references a signupDate field included on the triggering event or API call (not the signupDate on a user profile).

Example: relative dates in segmentation

This segmentation query specifies {{cutoffDate}}||-7d to select users who, starting seven days prior to cutoffDate, have no purchase events:

Relative date in segmentation

Since this segmentation query relies on {{cutoffDate}}, it can only be evaluated when there is a triggering event or API call that provides a value for cutoffDate. With segmentation queries like this, clicking Refresh Results yields no results or an error (depending on the query), since there's no value to use for the Handlebars expression.

However, you can save these segmentation queries as dynamic lists, and target them with calls to POST /api/campaigns/trigger (making sure the request body also includes any values required by the segmentation query). For example, a request body sent to this endpoint might look similar to the following:

{
  "campaignId": 1115908,
  "listIds": [509075],
  "dataFields": {
    "cutoffDate": "2020-03-15 00:00:00 +00:00"
  }
}

In this example, 509075 is the ID of the dynamic list saved from the segmentation query that contains the {{cutoffDate}} Handlebars expression.

Example: Relative dates in a journey filter

This journey filter tile compares a user's birthday with {{ageDate}}||-25y to select users who, according to the ageDate field, are older than 25:

A relative date in a journey filter tile

To trigger this journey, you might call the POST /api/workflows/triggerWorkflow API, with a request body similar to the following:

{
  "email": "user@example.com",
  "workflowId": 1234567,
  "dataFields": {
    "ageDate": "2020-03-15 00:00:00 +00:00"
  }
}

NOTE

We recently renamed Workflows to Journeys—however, our APIs and field names still refer to them as "Workflows" (for example, workflowId). Continue to use the term "Workflows" in your API requests and responses.

Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

Support docs

Related articles