Date and time values appear across APIs, transactions, behavioural events, rewards, and event notifications. These values may be created in one timezone, processed in another, and consumed globally.

Capillary follows a consistent timezone handling model to ensure predictable behaviour across regions and systems.

This page explains how date-time values are accepted, stored, and returned across the platform.

Core principles

Capillary follows these rules across supported APIs and modules:

Accept date-time values in ISO 8601 format.
Return date-time values in ISO 8601 format.
Use the server timezone for GET API responses.
Preserve the original timezone offset when provided.
Store behavioural events in epoch milliseconds for global ordering.
Retain legacy fields for backward compatibility where required.

How timezone works across APIs and modules

POST and PUT APIs (input behaviour)

When you send date-time values:

Use ISO 8601 format.
Include a timezone offset if you want to preserve local context.
Where supported, provide timeZoneName in IANA format (for example, Asia/Shanghai).

If you include an offset, the system extracts and stores it separately in applicable modules.

GET APIs (response behaviour)

When you retrieve data:

Date-time values are returned in ISO 8601 format.
The server timezone is used.
Where applicable, the original input offset is returned in a dedicated field.

Format used:

yyyy-MM-ddTHH:mm:ssXXX

Examples:

2025-12-16T14:30:45Z
2025-12-16T14:30:45+05:30

Transactions

For transaction APIs:

billingTime is returned in server timezone.
billingTimeInputOffset preserves the original input offset.
Local-time promotion evaluation can use the preserved offset.

Behavioural events

For behavioural events:

eventDateTime is stored as epoch milliseconds.
eventDateTimeInputOffset preserves the original offset, if provided.
Epoch storage ensures accurate global ordering.
The preserved offset enables correct local-time campaign evaluation.

Event notifications

For event notifications:

Date-time values are communicated in epoch milliseconds.
Where legacy fields exist, corresponding *InMillis shadow fields are provided.

Rewards catalog

Rewards use configuration-driven timezone behaviour:

By default, time-based calculations use server timezone.
If CONF_ENABLE_ORG_TIMEZONE is enabled, calculations use the organisation’s timezone.
Historical data is not retroactively modified.

Timezone behaviour summary

Area	Status	Timezone behaviour	Notes
POST / PUT APIs	Standardised	Accept ISO 8601 date-time	`*ISO` fields provided for legacy compatibility
GET APIs	Standardised	Return ISO 8601 date-time in server timezone	Default response format
Transactions (GET)	Standardised	Server timezone + offset preserved	`billingTimeInputOffset` returned
Behavioural events	Standardised	Epoch milliseconds + offset preserved	`eventDateTimeInputOffset` returned
Event notifications	Standardised	Epoch milliseconds	`*InMillis` shadow fields provided
Rewards catalog	Configuration-driven	Server timezone by default	Organisation timezone if config enabled
v1 APIs	Not yet supported	Legacy behaviour retained	Timezone standardisation not applied
Insights, Badges UI, Offers (UI & API)	Not yet supported	Existing behaviour retained	Timezone standardisation not yet available