POST and PUT APIs in detail

Selected POST and PUT APIs accept date-time values in ISO 8601 format. The following rules apply when sending date-time values.

Format requirement

All explicitly passed date-time values must follow ISO 8601 format with the local date, time, and UTC offset concatenated:

2026-03-25T17:12:00+05:30

When a timezone offset is included

The system extracts the offset from the value automatically and stores it separately alongside the converted server-timezone value. You do not need to pass it in a separate field.

When no offset is included

The value is processed without timezone context. No offset is stored. The server applies its own timezone during storage.

Using `timeZoneName` for DST-aware recording

For APIs that support it, pass timeZoneName in IANA format to record the timezone used during entity creation:

"timeZoneName": "Asia/Shanghai"

This value is stored against the entity and returned in subsequent GET API responses (for example, in Get Target Groups). It ensures that time-based evaluations — such as promotion windows — can account for DST transitions correctly. There is no validation on this field; it is a reference label.

Autogenerated times

Autogenerated timestamps such as audit log entries and system-created dates are handled internally. You do not need to provide an offset for these. Only explicitly passed values such as billing dates or event dates require ISO 8601 format with an offset.

Using ISO shadow fields

When timezone is enabled, use ISO-formatted fields such as startDateISO and endDateISO. Do not send the legacy field and its ISO shadow field in the same payload.

API behaviour summary

API type	Accepted format	Notes
POST / PUT (date-time fields)	ISO 8601 with offset	Offset extracted and stored automatically if included.
POST / PUT (`timeZoneName`)	IANA format string	Stored as a reference label. Returned in GET responses. No format validation.
POST / PUT (legacy fields)	Legacy format retained	`*ISO` shadow fields provided for new integrations. Do not send both in the same payload.

Offset preservation in detail

Transactions

The offset is extracted from the billing date-time in the request and stored internally in the extended field event_input_date_offset. It is returned in GET responses as billingTimeInputOffset.

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

If the billing date includes an offset and you also manually send event_input_date_offset, the system ignores the manually provided value. If the billing date has no offset and you manually provide event_input_date_offset, the system uses the provided value.

Behavioural events

Input provided	Example	`eventDateTimeInputOffset` in response	What Capillary does
Date-time with timezone offset	`2024-08-24T15:30:00+07:00`	`+07:00`	Extracts and stores the `+07:00` offset.
Date-time without timezone information	`2024-08-24T15:30:00`	No	No offset stored.
Date-time with UTC notation (`Z`)	`2024-08-24T15:30:00Z`	`+00:00`	Normalises to `+00:00` and stores it.
Date-time is missing or null	`null`	No	No offset stored.

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

Insights timezone configuration

Timezone normalization in Insights is controlled by the org-level flag ENABLE_INSIGHTS_TIMEZONE_CONVERSION. By default, this is set to FALSE.

When disabled: Insights displays timestamps as stored. Values may vary by source.
When enabled: Insights normalizes all timestamps to the server timezone before generating report dimensions, using the Till → Store → Zone → Org hierarchy.

Enabling the flag affects only newly processed data from the point of enablement. Existing historical data is not automatically updated. Enabling without a full data reload produces a mix of pre- and post-normalization timestamps, which can cause inconsistencies in time-based queries.

For new data sources or reporting tables onboarded into Insights, ensure timestamp columns are correctly registered in the source column timezone config as part of the standard onboarding checklist.

To enable, raise a request with the Capillary Product Support team.

Timezone resolution hierarchy

The Till → Store → Zone → Org hierarchy is used to resolve timezone for a specific set of fields — primarily in Insights and for certain API-level evaluations. It is not applied universally across all database writes.

Resolution order

When timezone resolution is required, Capillary checks each level in order and uses the first timezone it finds:

Till → Store → Zone → Org default timezone

If no timezone is configured at any level, the server timezone is used as the fallback.

Zone timezone

Navigate to Organization Settings > Master Data Management > Store Masters > Zones. Set the Default Time Zone when creating or editing a zone. For bulk creation, import zones using a CSV file that includes a Time Zone ID column. See Create zone.

Store timezone

Navigate to Organization Settings > Master Data Management > Store Masters > Stores. Set the Store Default Time Zone when creating or editing a store. See Create store.

Till timezone

Configure using the Add Till API or retrieve using the Get org till details API. The timeZoneId field on the till record defines its timezone.

Organization base timezone

Set in Organization Settings > Organization Profile > Set Org TimeZone. This timezone is used as the final fallback when no till, store, or zone timezone is configured.

Several modules instead write date-time values directly in the store timezone at the time of the event and are not resolved through the hierarchy:

Module	DB table / entity	Field
Coupons	CouponEntity	`issuedDate`
Coupons	CouponRedemptionEntity	`redeemedDate`
Coupons	RedemptionSummaryCouponUserEntity	`redeemedDate`
Coupon series	CouponSeriesEntity	`validTillDate`, `redemptionValidFrom`, `dvsExpiryDate`, `created`
EMF	customer_enrollment	`enrollment_date`, `termination_date`, `last_slab_change_date`, `slab_expiry_date`
EMF	points_awarded (+ bill/lineitem/promotion/tender)	`awarded_date`, `expiry_date`
EMF	partner program enrollment	`enrolled_on`, `current_slab_expiry_date`, `last_slab_change_date`
Incentives	earned promotions	`eventTime`, `validTill`
Incentives	issued promotions	`issuedTime`, `validTill`

Extended fields: timezone resolution detail

DateTime and Timestamp type

DateTime and Timestamp extended field values are converted to the server timezone on write and returned as stored (server timezone) on GET.

Supported input formats

Examples shown for the India cluster:

Input format	Example value	Interpretation	Saved in DB (UTC)	Shown in Member Care
`yyyy-MM-dd`	`1986-07-15`	Time assumed as 00:00:00 UTC	`1986-07-15T00:00:00.000+00:00`	`1986-07-15T05:30:00+05:30`
`yyyy-MM-ddTHH:mm:ssZ`	`1986-07-15T00:00:00Z`	Exact UTC timestamp	`1986-07-15T00:00:00.000+00:00`	`1986-07-15T05:30:00+05:30`
`yyyy-MM-ddTHH:mm:ssZ`	`1986-07-15T14:30:00Z`	Exact UTC timestamp	`1986-07-15T14:30:00.000+00:00`	`1986-07-15T20:00:00+05:30`
`yyyy-MM-ddTHH:mm:ss+05:30`	`1986-07-15T14:30:00+05:30`	Local time with offset	`1986-07-15T09:00:00.000+00:00`	`1986-07-15T14:30:00+05:30`

Do not send DateTime or Timestamp extended field values as raw epoch milliseconds. If you send a value such as 1769889600000 without an offset, the system treats it as UTC and converts it to the server timezone, causing a time shift that can result in incorrect promotion evaluation.

Format	Example	Behaviour
Epoch (no offset)	`"show_time": 1769889600000`	Treated as UTC, converted to server timezone — time shifts
ISO 8601 with offset	`"show_time": "2026-01-31T20:00:00-06:00"`	Interpreted as local time, no conversion applied

Date type

Date-type extended fields are controlled by the configuration CONF_DATE_EF_TZ_FIX_ENABLED.

Without this configuration, the system stores dates as timestamps at midnight UTC. When the server converts these to the server timezone, the displayed date can shift by one calendar day. For example, a date stored as 2023-10-27 00:00:00 UTC on a UTC-8 server appears as 2023-10-26.

When CONF_DATE_EF_TZ_FIX_ENABLED is enabled, the system treats Date fields as pure calendar dates in UTC and does not apply server timezone conversion. 2023-10-27 remains 2023-10-27 across all timezones.

This configuration applies only to Date-type extended fields. DateTime and Timestamp fields continue to respect timezone conversions regardless of this setting. To enable, raise a request with the Capillary Product Support team.

Rewards catalog timezone configuration

By default, all time-based calculations in the rewards catalog use the server timezone. The configuration CONF_ENABLE_ORG_TIMEZONE changes this to use the organization timezone instead.

Scenario	Default behaviour (disabled)	Behaviour when enabled
Time calculation	Server timezone.	Organization timezone.
Reward start/end	May not match intended local time.	Follows org timezone exactly.
Daily limit reset (fixed window)	Resets at midnight server time.	Resets at midnight org timezone.
Weekly/monthly limit windows	Start based on server calendar.	Start at midnight on the first day of the period in org timezone.

When CONF_ENABLE_ORG_TIMEZONE is enabled, DST transitions are handled automatically using the organization's IANA timezone. This configuration does not retroactively modify historical data. During data migration, validity periods of historical rewards are interpreted in the organization timezone.

To enable, create a JIRA ticket for the Capillary Product Support team.

Optional: 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. Raise a request with the Capillary Product Support team to enable CONF_ORG_DISABLE_MACHINE_TIME_CONV.

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

Billing time input	v2 GET response
`2026-01-23T09:00:00+05:30`	`2026-01-23 09:00:00`