General concepts and standardization

What is the standard format for external APIs?

All external APIs use ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssXXX. This format includes the timezone offset and avoids parsing ambiguity.

Why not store everything in the user's local time?

Storing only local time creates ambiguity. During daylight saving transitions, jobs can run twice or not at all. Storing in a consistent reference timezone enables accurate comparison, sorting, and calculations across regions.

Does the system handle the ambiguous hour during DST fall-back?

No. The system does not handle the repeated 01:00–01:59 hour during a DST fall-back. See DST fall-back handling for details.

Implementation and feature gating

Is timezone support enabled for all organizations by default?

Yes. Timezone standardisation across APIs is enabled for all organizations.

API and integration

Do all services and member APIs need to follow the new timezone standard?

Yes. All new integrations must follow the ISO 8601 format and use V2 APIs. V1.1 APIs have not been updated to support the standardized timezone model and retain their existing behaviour.

Which fields should I use when sending date-time values?

When timezone is enabled, use ISO fields such as startDateISO and endDateISO. Do not send legacy fields such as startDate in the same payload.

How should autogenerated times be handled compared to explicitly passed times?

For explicitly passed times (such as a billing date or event date), the value must follow ISO 8601 format with the local date, time, and UTC offset concatenated. For example: 2026-03-25T17:12:00+05:30. Autogenerated times such as audit log timestamps are handled internally by the service and do not require the caller to provide an offset.

Does the server perform timezone conversion in responses, or does the client handle it?

Responses are returned in the server timezone. However, APIs also return a dedicated offset field (for example, billingTimeInputOffset) alongside the server-timezone value. This allows the client application or middleware to convert the server time back into the customer's original local timezone if needed.

Why is the offset field only available for behavioural events and transaction GET APIs and not all APIs?

Transactions and behavioural events were prioritized because they are the most time-sensitive for loyalty evaluation. Support for offset preservation in other areas will be extended in future releases. See also Offset preservation scope.

How does the system handle legacy tables that cannot be modified?

The system applies a reverse transformation at API response time and derives the timezone from the current store or till configuration. If that configuration changes later, historical API responses may also change.

Can I manually pass `eventDateTimeInputOffset`?

No. This field is system-generated. If you send it manually, the API rejects the request with HTTP 908.

Technical clarifications

How are date-time values stored in the database?

The system normalizes all date-time values to the server timezone before storage. This is required because the underlying database columns use MySQL DATETIME type, which does not natively support timezone offsets.

Is the original input offset lost after normalization?

No. The original offset is extracted from the input and stored separately as an extended field (event_input_date_offset). It is returned in GET API responses in the corresponding offset field (for example, billingTimeInputOffset).

Why store the offset instead of only storing UTC?

UTC enables accurate comparison. However, some workflows require displaying the exact original context of the event. Storing the offset preserves the event's geographical and audit context.

Does the client need updated DST rules?

Yes. If the client uses outdated DST rules, it may send an incorrect offset. Once the platform receives a correct offset, it converts and stores the internal moment accurately.