Dates can be stored several ways — as UTC timestamps, as local-timezone timestamps, or as date-only values. Knowing the convention prevents the classic “the date is one day off” surprise after a server move.
Storage Conventions
- UTC always (recommended): Every stored timestamp is UTC. The platform converts to/from the viewer's timezone at display time. No ambiguity, no DST surprises.
- Site-local timezone: Timestamps stored in the site's timezone. Simple while the site stays in one place; fragile if the timezone ever changes.
- Date-only (no time): Days like “invoice due 2026-05-13”. No timezone needed; interpreted as the user's day.
Display Conversion
- Read the UTC timestamp from the database.
- Determine the viewer's timezone (their preference, falling back to the site default).
- Convert the UTC value to the viewer's zone for display.
- Format using the viewer's date format preference.
API Behaviour
- API responses include timestamps in ISO-8601 with explicit UTC offset (
2026-05-13T14:32:00Z). - API inputs accept any ISO-8601 with offset; converted to UTC for storage.
- Inputs without an offset are interpreted as the site's timezone (with a warning logged).
Worked Examples
- Cross-zone team: Manager in London creates a task at 14:00 BST. Engineer in San Francisco sees it timestamped 06:00 PDT — same moment, different display.
- Date-only field: “Birthday” field stores 1990-05-13 — same value regardless of who's looking.
- DST transition: Job scheduled for 02:30 local time on the “spring forward” day — when the clock skips from 01:59 to 03:00, the job runs at 03:00 (and a warning logged).
- Cross-server migration: Platform moves from EU server to US server. Because stored times are UTC, nothing shifts — only the default display zone needs updating.