Datetimes
Learn how to format datetimes for Klaviyo's APIs.
Date and timestamp support
Note that event datetimes sent via the legacy v1/v2 endpoints support Unix timestamps in addition to datetime ISO 8601 formats. However, our new APIs do not support Unix timestamps. It is recommended that you convert the Unix timestamp to a supported ISO 8601 format. See the MDN docs on the toISOString() method for more details on conversion.
Datetime formatting
All datetimes across all new APIs in URLs, requests, and response bodies must use the ISO 8601 RFC 3339 format, such as YYYY-MM-DDTHH:MM:SS.[mmm]. Note that the letters used in the datetime syntax must always be uppercase. Some examples include:
2023-08-15T12:30:002023-08-15T12:30:00Z2023-08-15 12:30:00Z2023-08-15T12:30:00+03:00
For more information on recognized formats, refer to our acceptable date and timestamp formats guide for profile and event properties.
URI encoding
Datetimes can contain non-URL-safe characters. To combat this, we recommend that you always URI-encode your datetime values. Refer to the MDN docs on encodeURIComponent for more details.
Example request and response
In this example, we have requested all events that have a datetime greater than 2023-08-07T12:30:00.710Z:
curl --request GET \
--url 'https://a.klaviyo.com/api/events/?filter=greater-than(datetime,2023-08-07T12:30:00.710Z)' \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-07-15'
{
"data": [
{
"type": "event",
"id": "4vGfpcpPRGL",
"attributes": {
"timestamp": 1692028246,
"event_properties": {
"custom_value": "newer event time value",
"$event_id": "YjpZcE"
},
"datetime": "2023-08-14 15:50:46+00:00",
"uuid": "55084f00-3aba-11ee-8001-a3e96a3d92dc"
},
"relationships": {
"profile": {
"data": {
"type": "profile",
"id": "01H7TBW70G8RYXHF9D91K4W72J"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/relationships/profile/",
"related": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/profile/"
}
},
"metric": {
"data": {
"type": "metric",
"id": "TQpx2b"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/relationships/metric/",
"related": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/metric/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/"
}
},
{
"type": "event",
"id": "4uQsGyFKUGn",
"attributes": {
"timestamp": 1691523702,
"event_properties": {
"custom_value": "custom val",
"$event_id": "1691523702"
},
"datetime": "2023-08-08 19:41:42+00:00",
"uuid": "995f9f00-3623-11ee-8001-b91e24a90599"
},
"relationships": {
"profile": {
"data": {
"type": "profile",
"id": "01H6PJY17J72TV4EWXZPS1XYX7"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/relationships/profile/",
"related": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/profile/"
}
},
"metric": {
"data": {
"type": "metric",
"id": "QV8sPg"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/relationships/metric/",
"related": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/metric/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/"
}
}
],
"links": {
"self": "https://a.klaviyo.com/api/events/?filter=greater-than(datetime,2023-08-07T12:30:00.710Z)",
"next": null,
"prev": null
}
}
Additional resources
Updated over 1 year ago