Time Zone

The site time zone determines how dates and times are interpreted when stored, calculated and displayed. Get it right at install and you avoid endless “why does this say 3 hours ago?” confusion.

How the Setting Is Used

• Scheduled jobs: Cron expressions are interpreted in this timezone unless overridden per job.
• Audit timestamps: Internal logs use this timezone when no user is signed in.
• Default user timezone: New users inherit this; they can override in their preferences.
• Date-only fields: Stored without a timezone but interpreted as “midnight in this zone”.
• Reports: Aggregations like “orders today” use this zone to define the day boundary.

Recommended Values

• UK-based platform: Europe/London.
• US East Coast: America/New_York.
• US West Coast: America/Los_Angeles.
• EU multi-country: Often Europe/Brussels or UTC.
• Global platform: UTC — neutral, no DST confusion.

UTC vs Local

Many engineers default to UTC for clarity and DST avoidance. Many product teams default to local time so business reports match what stakeholders expect. There's no single right answer — but pick one philosophy and stick to it.

Worked Examples

• UK SaaS: Europe/London. Business reports show the UK day clearly; daylight-savings is handled automatically.
• Global platform: UTC. All scheduled jobs are unambiguous; users see their local time per their preference.
• Multi-region tenant: Each tenant overrides; reports for the German tenant show their local day, US tenant shows theirs.
• Cross-time-zone team: UTC site default; users in different countries see localised times in the UI but APIs return ISO with offsets.

Warning: Don't switch the platform-wide timezone after data exists. Historical timestamps will appear to “shift”. If you must, document and communicate clearly.

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

1. Read the UTC timestamp from the database.
2. Determine the viewer's timezone (their preference, falling back to the site default).
3. Convert the UTC value to the viewer's zone for display.
4. 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.