This page provides you with information on handling timezone in behavioural events.
When a behavioural event is received, Capillary captures the moment the customer action occurred and processes it in a consistent and predictable manner.
What happens when an event is received
- The event date and time represent the exact moment the action occurred.
- Capillary converts this value into a standard timestamp (epoch milliseconds) for consistent processing across regions.
- If the input date-time includes a timezone offset, the original local offset is preserved separately.
This ensures that:
- Events are processed in the correct order globally (true sequence in which events happened worldwide, independent of local timezones).
- The original local time context of the customer action is not lost.
- Downstream systems can evaluate events using the correct local time.
Behaviour of event date-time fields
| Field | Description |
|---|---|
| eventDateTime | Stores the event time as a standard timestamp (epoch milliseconds). |
| eventDateTimeInputOffset | Stores the original timezone offset from the input date-time, if provided. |
Common input scenarios and system behaviour
The table below explains how Capillary handles different types of event date-time inputs.
| Input provided | Example | eventDateTimeInputOffset in response | What Capillary does |
|---|---|---|---|
| Date-time with timezone offset | 2024-08-24T15:30:00+07:00 | Yes - +07:00 | Extracts and stores the +07:00 offset. Event is processed normally. |
| Date-time without timezone information | 2024-08-24T15:30:00 | No | Processes the event normally. No offset is stored. |
Date-time with UTC notation (Z) | 2024-08-24T15:30:00Z | Yes- 00:00 | Normalises the timezone to +00:00 and stores it. |
| Date-time is missing or null (if optional) | null | No | Processes the event without errors. No offset is stored. |
Example: Behavioural event with timezone offset
Input event
{
"eventDateTime": "2024-08-24T15:30:00+07:00"`
}Processed event
{
"eventDateTime": "1724488200000",
"eventDateTimeInputOffset": "+07:00"
}What this means
- The event occurred at 15:30 in the customer’s local timezone (+07:00).
- Capillary converts the time to epoch milliseconds for consistent processing.
- The original local timezone offset is preserved separately.
Example use case: Behavioural event eligibility based on local time
Scenario
A brand runs a global campaign that triggers a reward when a customer adds an item to the cart between 9:00 PM and 10:00 PM local time. The Capillary server processing the event is located in a region that uses UTC (+00:00).
A customer adds an item to the cart at:
2024-08-24T21:45:00+05:30
This indicates the action happened at 9:45 PM in the customer’s local timezone.
How Capillary provides the data
When the behavioural event is processed, Capillary returns:
eventDateTime: 1724516100000
eventDateTimeInputOffset: +05:30
eventDateTimerepresents the exact moment of the action in a standard, timezone-neutral format.eventDateTimeInputOffsetpreserves the original local timezone offset.
How the downstream application evaluates this
The campaign or promotion engine:
- Uses
eventDateTimeto process events in the correct global order. - Uses
eventDateTimeInputOffsetto reconstruct the local event time as:
21:45 (local time)
Result
- The add-to-cart action is correctly recognised as occurring within the 9:00–10:00 PM local window.
- The campaign trigger fires as expected.
- The customer receives the intended reward or communication.
What would happen without the offset
Without eventDateTimeInputOffset, the system would evaluate the event using server time (16:15 UTC).
This could fall outside the campaign window, causing the action to be ignored and the customer to miss the reward even though they acted on time locally.