Unix Timestamp vs ISO 8601: How to Store Dates

Unix seconds        1700000000
Unix milliseconds   1700000000000
ISO 8601, UTC       2023-11-14T22:13:20Z
ISO 8601, offset    2023-11-15T03:43:20+05:30

All four describe the same instant. Unix timestamps are compact and easy to compare and do arithmetic on, but unreadable and ambiguous about their unit. ISO 8601 strings are readable and carry their time zone offset, but are longer and easy to compare wrongly as text.

The classic one is mixing seconds and milliseconds. JavaScript's Date expects milliseconds, while most backends, databases and JWTs use seconds:

new Date(1700000000).toISOString();        // "1970-01-20T16:13:20.000Z"   wrong unit
new Date(1700000000 * 1000).toISOString(); // "2023-11-14T22:13:20.000Z"   correct

A date in January 1970 in your data almost always means seconds were read as milliseconds. Name the unit in the field, as in createdAtMs or expires_at_s, or agree on one unit for the whole API.

ISO 8601 strings sort correctly as text only when every value uses the same format and the same offset. With mixed offsets, string order and time order disagree:

["2026-10-18T09:15:00Z", "2026-10-18T10:00:00+02:00"].sort();
// both stay in this order as text, but 10:00+02:00 is 08:00 UTC, which is earlier

Write timestamps in UTC with a Z suffix and fixed precision, and convert to local time only for display. Then sorting and comparing strings gives the right answer.

from datetime import datetime, timezone

datetime.fromtimestamp(1700000000)                   # 2023-11-15 03:43:20  local time, no zone
datetime.fromtimestamp(1700000000, tz=timezone.utc)  # 2023-11-14 22:13:20+00:00
datetime.now(timezone.utc).isoformat()               # aware, safe to serialise

Without tz, Python returns a naive datetime in the server's local time, here India's +05:30, with no record of the zone. The same code on a server in another zone produces a different value. datetime.utcnow() is deprecated since Python 3.12 for the same reason; use datetime.now(timezone.utc).

Use the database's date type rather than a number or a string. In PostgreSQL that is timestamptz: it stores an exact instant in UTC and converts input with any offset:

select '2026-10-18 10:00:00+02'::timestamptz at time zone 'UTC';
-- 2026-10-18 08:00:00

Despite its name, timestamptz does not store the original zone, only the instant. If the local time zone matters, such as the zone a meeting was booked in, store it in a separate column.

• JSON APIs: ISO 8601 in UTC, such as 2026-10-18T08:00:00Z. Readable in logs and debuggers, unambiguous, and parsed by every language.
• Databases: the native type, timestamptz in PostgreSQL.
• Metrics, events and high-volume logs: Unix milliseconds, where size and fast arithmetic matter and the unit is fixed by the system.
• Tokens and protocols that specify a format: follow the specification. JWTs, for example, use Unix seconds.