# How Timezones Are Handled

The UTC storage model, the display conversion boundary, and the timezone policy applied to API payloads, exports, and generated documents.

**Category:** Concepts

**Last reviewed:** 5 August 2026

# How Timezones Are Handled

WinkPG records activity for merchants, resellers, and cardholders who are frequently in different timezones. To keep stored data unambiguous, the platform applies a single storage model and performs timezone conversion at exactly one boundary. This document specifies that model, defines the scope of the conversion boundary, and states the policy applied to each artifact that falls outside it.

## Value classes

Two classes of temporal value are handled differently throughout the platform. The class of a value determines whether conversion applies to it, so the distinction is worth establishing before the rules.

| Class | Definition | Examples | Converted for display |
|---|---|---|---|
| Instant | A specific point on the global timeline, carrying both a date and a time of day. | Authorization time, settlement time, webhook delivery time, last sign-in time. | Yes |
| Calendar date | A date with no time component, denoting a day rather than a moment. | Card expiration, invoice due date, recurring schedule start and end dates. | No |

## Storage and conversion model

The model consists of three rules.

1. **Every instant is stored in UTC** (Coordinated Universal Time). This applies to persisted records, values transmitted over the API, and values written into generated files.
2. **Conversion occurs only at display.** An instant is translated into a viewer timezone at the point it is rendered on screen for a signed-in user, and nowhere else. No stored value is rewritten as a consequence of a viewer preference.
3. **Calendar dates are never converted.** They are stored and returned as the day they denote.

The viewer timezone has one function outside display: **date range interpretation**. When a date range is supplied to a filter or a report, its bounds are interpreted as whole calendar days in the viewer timezone and then translated into the equivalent UTC window before the query executes. This determines which records fall within the range; it does not alter the records themselves. A request for March 1 through March 31 therefore returns the viewer's March rather than a UTC March beginning partway through the viewer's February 28.

## Display conversion and labeling

A converted instant is normally accompanied by a timezone label identifying the zone it was converted into. A transaction rendered as `3/14/2026 9:30 AM EDT` has been translated from its stored UTC value into the viewer timezone, and the suffix identifies that zone.

**Labels are computed per instant, not per session.** The abbreviation reflects the offset in effect at the moment being displayed, so a January record renders as `EST` and a July record renders as `EDT` within the same list. This is a correct representation rather than an inconsistency: the two records occurred under different UTC offsets, and applying the current offset uniformly would misstate one of them.

A small number of density-constrained surfaces, such as activity timelines and compact detail panels, omit the repeated label once the surrounding screen has established the applicable timezone. Values on those surfaces are converted on the same terms as elsewhere.

**An unconverted value is labeled explicitly.** Where a surface deliberately presents UTC (see "Exports and generated documents"), the value carries a `UTC` marker so that it cannot be misread as viewer local time.

The timezone currently in effect is stated in the page footer beside a clock icon, and selecting it navigates to the setting that governs it. The footer reports the zone actually being applied, irrespective of how it was resolved. A footer reading `UTC` indicates that the effective offset is zero; it does not distinguish between an explicit UTC preference, a fallback, and any other zone at zero offset. The account settings page reports the stored preference itself, including whether one has been set.

## Calendar dates

Calendar dates are exempt from conversion in both directions: the day submitted is the day stored, and the day stored is the day rendered, regardless of viewer timezone.

The exemption is deliberate. A date-only value has no time component from which an offset can be meaningfully applied. Converting one would displace it by a full day for any viewer west of UTC, so an invoice due on the first of the month would begin to render as due on the final day of the preceding month.

In summary: a value carrying a time of day is subject to conversion and labeling; a bare date is not.

## Timezone resolution

### User preference

The per-user preference is set in **My Account** (`/MyAccount/Manage`) on the **General** tab, in the Time Zone card. The card reports the zone currently in effect and accepts a replacement from the supported list. No elevated permission is required, as the setting governs presentation only and has no effect on stored data or on other users.

A saved change takes effect immediately. Values already rendered on the current page, including those inside lists and grids, are re-rendered in the new zone without a reload. A concurrently open session in a second tab or window continues to apply the previous zone until it reconnects; reloading that session adopts the new value.

### Clearing the preference and the fallback chain

Clearing the preference does not select UTC. It removes the personal override and returns the account to the applicable default, resolved in the following order:

1. Merchant default
2. Reseller default
3. Tenant default
4. UTC

UTC is therefore the terminal fallback, applied only when no default is configured at any level above the user. Clearing is appropriate where an organization has established a suitable default and a personal override is no longer wanted.

### Administrative default

The organization-wide default is configured on the **Time Zone** tab of **Settings** (`/setting-management`). This is a distinct scope with a distinct audience: it establishes the fallback for every user who has not set a personal preference, and access to it is gated behind an administrative permission. It is not the mechanism for changing an individual user's own timezone.

## Automatic detection and mismatch handling

Because most users do not visit a settings page, the platform queries the browser for its reported timezone once per session. The resulting behavior depends on whether a stored preference exists.

| Condition | Behavior |
|---|---|
| No stored preference | The browser timezone is adopted and a confirmation notice states the zone now in use. No further action is required. |
| Stored preference matching the browser | No notice is shown. |
| Stored preference not matching the browser | A warning identifies both zones and offers a single-action switch alongside an equally available option to retain the existing preference. |

Two constraints govern this behavior.

**No preference is modified without explicit acceptance.** A deliberately chosen timezone remains in effect until the switch is accepted. Signing in from a different location does not silently overwrite a stored preference.

**The comparison is on clock equivalence, not on identifier.** Two zones that report differing identifiers but display the same time as one another, both currently and at future points in the year, do not constitute a mismatch and produce no prompt. Zones that genuinely differ, such as Denver and Phoenix, are correctly identified as a mismatch.

Declining the prompt suppresses it for the remainder of the browser session, so it does not recur during navigation between pages. It reappears in a subsequent session, or earlier if the browser begins reporting a timezone other than the one previously declined.

Detection is a convenience mechanism and is not required for correct operation. If the browser does not supply a timezone, the platform continues to function and the stored preference is unaffected.

## API datetime handling

The API applies the same UTC posture. Instants are accepted, stored, and returned as UTC, and no response is adjusted to the timezone of the authenticated user.

| Direction | Behavior |
|---|---|
| Request value with an explicit offset (`2026-03-14T09:30:00-05:00`, or a trailing `Z`) | The offset is honored and the value is converted to the equivalent UTC instant before storage. This is the supported form. |
| Request value with no offset (`2026-03-14T09:30:00`) | Underspecified and not suitable for production use. Most fields interpret a bare value as UTC and store it unchanged; fields typed to carry an offset instead resolve the value against a default offset rather than assuming UTC. Supply an offset in all cases. |
| Response values | UTC instants. Fields that carry an offset express it as zero (`2026-03-14T14:30:00+00:00`); fields that do not carry the `Z` designator (`2026-03-14T14:30:00Z`). The two forms denote the same instant. |

### Integration requirements

- **Always transmit an explicit offset,** or a trailing `Z` for UTC. A local wall-clock time submitted without an offset conveys an underspecified value rather than a determinate instant, and its interpretation depends on the field receiving it.
- **Parse responses with an offset-aware type.** Both `Z` and `+00:00` occur across the API and both denote UTC. A parser that accepts only one form will fail on the other.
- **Treat every response instant as UTC** and apply conversion within the consuming application at display time. No response reflects any particular user's timezone.
- **Expect divergence between the interface and the API** for the same underlying value. The interface presents a converted, labeled value; the API presents the stored UTC instant. Both denote the same moment.
- **Date-only fields follow the display rule.** A calendar date is transmitted and returned as the day it denotes, with no offset applied.

## Exports and generated documents

Artifacts produced outside a live screen must select a timezone explicitly, because the eventual reader may be unknown at generation time. The selections below are deliberate.

| Artifact | Timezone policy |
|---|---|
| Report exports (CSV, Excel) | The viewer timezone determines **row selection only**: the requested date range is interpreted as whole calendar days in that zone. Timestamps **within** the file are UTC, as produced by the report. |
| Grid exports (CSV, Excel) from a list screen | UTC, with `(UTC)` appended to date column headers so the file is unambiguous when opened in a spreadsheet application. |
| Transaction receipts | UTC, with an explicit `UTC` suffix on the timestamp. |
| Emailed notifications | UTC, stated in the message body. |

Report exports are the only artifact in which the viewer timezone has any effect, and that effect is confined to the range boundaries. Row values within the file are UTC on the same terms as every other generated artifact. When reconciling an exported report against a screen, expect the on-screen value to be converted and the exported value to be UTC.

The remaining artifacts are UTC without exception because each may be regenerated at a later time, delivered by webhook, or presented to a cardholder in another jurisdiction. A timestamp whose value depended on the identity of the party who generated it would be less reliable than one that is consistently UTC.

The governing principle: **where WinkPG cannot determine who will read a document, it emits UTC,** and labels the value as UTC wherever the output format provides a location for a label (a column header, a suffix on the value, or a line in the message body).

## Reconciling apparent discrepancies

**A transaction time here differs from the time reported by a terminal or bank statement.**
Compare the timezone label on this value against the timezone in which the other system reports. The underlying instant is generally identical; the two systems are expressing it in different frames of reference.

**A timezone preference was changed, but an export is still in UTC.**
This is the specified behavior. All generated files, including report exports, write timestamps in UTC. The viewer timezone determines which days a report covers, not how timestamps within it are expressed.

**A single list shows `EST` on some rows and `EDT` on others.**
Labels are computed per instant. Records on opposite sides of a daylight saving transition occurred under different UTC offsets, and representing that is more accurate than applying the current offset to historical data.

**A preference was cleared and all values now display in UTC.**
No default is configured at the merchant, reseller, or tenant level, so the terminal fallback applied. Either set a personal preference or request that an administrator configure the organization-wide default.

**Whether the viewer timezone affects report and filter results.**
For date ranges, it does, by design. A range is interpreted as whole calendar days in the viewer timezone and then translated to UTC for the query, so a request for the previous day returns the viewer's day rather than a UTC day beginning partway through the viewer's afternoon.

## See also

- [All documentation](https://docs.winkpg.io/llms.txt): the machine-readable index of every public page on this site.