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 specificcolor
. - A journey might filter out all users whose
age
is less than{{age}}
. A triggering API call or event can then include a threshholdage
.
In some cases, it's helpful to use this approach to segment or filter users based on a date range. For example:
-
A campaign might target a dynamic list
that selects users who have not made any purchases within one week of a
cutoffDate
provided by the triggering API call. -
A journey might filter out
users who are younger than 25 on a particular
ageDate
, which is specified by the triggering API call or custom event.
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
:
-
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
orH
- 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 is2021-02-28
-
2020-03-31
minus one month is2020-02-29
-
2020-02-28
minus one month is2020-01-28
-
2020-02-29
minus one month is2020-01-29
-
2020-04-01
minus one month is2020-03-01
-
2020-05-01
minus one month is2020-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 byupcomingEventDate
(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 withgrandOpening
-
{{cutoffDate}}||-1M
- One month beforecutoffDate
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 to2020-03-01 14:00:00 -0400
. - A journey-triggering API call provides a
date2
value of2020-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:
- 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 asignupDate
field included on the triggering event or API call (not thesignupDate
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:
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:
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