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

eventDateTime represents the exact moment of the action in a standard, timezone-neutral format.
eventDateTimeInputOffset preserves the original local timezone offset.

How the downstream application evaluates this

The campaign or promotion engine:

Uses eventDateTime to process events in the correct global order.
Uses eventDateTimeInputOffset to 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.