General concepts and standardization

1. 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.

2. 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.

3. 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

4. Is timezone support enabled for all organizations by default?

For organizations created from 2026 onwards, it is enabled by default. For older organizations, timezone behaviour is gated using the TIMEZONE_ENABLED feature flag. Organizations without this flag continue with legacy behaviour.

API and integration

5. 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.

6. 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.

7. 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.

8. 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.

9. 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.

10. 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.

11. What happens if a database error occurs during timezone resolution?

The system resolves timezone in this order: Till → Store → Zone → Org. If a timeout or exception occurs, some modules historically fell back to the server timezone, which could produce inconsistent results for events from the same source. The Timezone Standardization initiative is designed to eliminate this non-deterministic fallback.

12. 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

13. 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.

14. 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).

15. 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.

16. How does the platform handle existing data?

The standard applies strictly to new products. For legacy data, the system uses reverse transformations and shadow fields (for example, dateISO alongside date). This approach avoids breaking existing integrations.

17. 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.

Business logic and edge cases

18. If a customer travels between timezones, should the UI adapt the display of their transaction history?

Because the system preserves the original offset, no information is lost. This gives organizations flexibility: the UI can either display the transaction in the original timezone in which it occurred, or dynamically convert it to the user's current location. The choice is left to the organization's display logic.

19. Should the implementation logic be different for APIs and notifications versus internal background schedules?

Yes. The design distinguishes between two layers. APIs and event notifications serve external integrators and must follow the standardized timezone model consistently. Internal background schedules and product workflows may operate differently and are handled separately within the platform.