Capillary follows a consistent model for handling date and time values across APIs. This ensures predictable behaviour for integrations across regions and clusters.

ISO 8601 response format

All GET APIs return date and time fields in ISO 8601 format using the server timezone.

Format used:

yyyy-MM-ddTHH:mm:ssXXX

Examples:

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

ISO-compliant fields across APIs

Capillary ensures ISO-compliant date-time representation across APIs.

Where a legacy field does not follow ISO 8601 format:

An additional *ISO field is provided.
The original field is retained for backward compatibility.
Both fields may exist in the response.

Example

Field	Behaviour
`ledgerCreatedDate`	Legacy format retained
`ledgerCreatedDateISO`	ISO 8601 representation

Integration guidance For the integrations, use the ISO-formatted fields.

POST / PUT API: date-time input

Selected POST and PUT APIs accept date-time values in ISO 8601 format.

For APIs that support timezone reference recording:

The timeZoneName field accepts a timezone value in IANA format (for example, Asia/Shanghai) and enables solving complications that arise during Daylight Saving Time (DST) transitions.
This value records the timezone used during entity creation.
It is returned in subsequent GET APIs.

Example:

"timeZoneName": "Asia/Shanghai"

API timezone behaviour summary

API type	Timezone handling	Notes
Selected POST / PUT APIs	Accept date-time values in ISO 8601 format.	For legacy fields that did not follow ISO format, additional `*ISO` shadow fields are provided. Existing fields remain unchanged for backward compatibility. Example: `startOnISO` in the Badges creation API.
Selected POST / PUT APIs	Accepts timezone value in IANA format . For example, `Asia/Shanghai`.	This value records the timezone used during entity creation. It is stored and returned in subsequent GET APIs (for example, Get Target Groups). This enables solving the complications that arise during DST transitions.
GET APIs	All date-time fields are returned in the server timezone.	Responses use ISO 8601 format (`yyyy-MM-ddTHH:mm:ssXXX`). Examples: `2025-12-16T14:30:45Z`, `2025-12-16T14:30:45+05:30`

📘
Note
Date and time fields inside extended fields are returned as stored. No additional conversion is applied.

Handling of date and time in transaction APIs

Transaction APIs capture the billing time when a transaction is created. During retrieval, Capillary:

Returns the billing time in the server timezone
Preserves the original input timezone offset, if provided

This ensures consistent processing while retaining local time context.

How transaction time is returned

If the input billing date includes a timezone offset, Capillary extracts and preserves that offset automatically.

Fields returned in Transaction GET APIs

Field	Description
`billingTime`	Transaction time converted to the server timezone
`billingTimeInputOffset`	Original timezone offset extracted from the input billing date

How the offset is captured

The offset is automatically extracted from the billing date-time in the request (for example, 2026-01-23T09:00:00+05:30).
- It is stored internally in the extended field event_input_date_offset.
- It is returned in GET responses as billingTimeInputOffset.
📘
Notes
- If the billing date includes an offset and you manually send event_input_date_offset, the system ignores the manually provided value.
- If the billing date does not include an offset and you manually provide event_input_date_offset, the system uses the provided value.

Offset behaviour by input type

Input scenario	`billingTimeInputOffset` in response	`event_input_date_offset` stored
Input includes offset (`+07:00`)	Yes	Yes
Input has no offset (`2021-11-10 23:00:49`)	No	No
Input offset is `+00:00`	Yes (`+00:00`)	Yes (`+00:00`)
Offset is null or empty	No	No

Example use case: Reward eligibility based on local time

Scenario

A brand runs a global promotion that awards bonus points for transactions made between 9:00 AM and 11:00 AM local time. The Capillary server processing the transaction is located in a region that uses UTC (+00:00).

A customer makes a purchase at:

2026-01-23T09:00:00+05:30 (billing time)

How Capillary provides the data

When the transaction is retrieved, Capillary returns:

billingTime: 2026-01-23T03:30:00Z (server time)

billingTimeInputOffset: +05:30

How the downstream application evaluates this

The rewards engine:

Uses billingTime to process the transaction in the correct global order.
Uses billingTimeInputOffset to reconstruct the local transaction time as:

09:00 (local time).

What would happen without the offset

Without billingTimeInputOffset, the system would evaluate the transaction using server time (03:30 UTC), which could fall outside the promotion window.

Optional configuration: Disabling automatic timezone Conversion (V2 APIs only)

If required, you can disable automatic conversion of transaction time to the server timezone for v2 Transaction APIs.

To enable this behaviour, raise a request with the Capillary Product Support team to activate the configuration:

CONF_ORG_DISABLE_MACHINE_TIME_CONV

When this configuration is enabled:

The billing time from the request payload is stored as provided.
No conversion to UTC or server timezone is performed.
The UTC offset in the input is not applied during storage.

This configuration applies only to v2 Transaction APIs and should be enabled only after assessing its impact on downstream integrations.

See the table below for an example.

Billing time	V2 GET (V2 API response)
2026-01-23T09:00:00+05:30	2026-01-23 09:00:00)