Overview
Unix timestamps and ISO 8601 strings both describe time, but they solve different problems. A Unix timestamp is compact and numeric, which makes it excellent for comparisons, expiration checks, queues, logs, and database indexes. ISO 8601 is readable and self-describing, especially when it includes a timezone offset such as Z for UTC.
This guide focuses on practical implementation choices: how values should be stored, how they should cross API boundaries, and where developers most often introduce timezone or precision bugs. The safest pattern is to keep the stored value unambiguous, document the unit, and format the date only when it reaches a human-facing interface.
When to use it
Use Unix seconds or milliseconds when you need arithmetic, fast sorting, compact payloads, or compatibility with existing epoch-based systems. Use ISO 8601 when humans read the value, when APIs need clarity, or when timezone offsets should travel with the date.
For production systems, also consider how the value will be indexed, logged, serialized, and read by other teams. A timestamp field that is obvious in one programming language can become ambiguous when it is consumed by JavaScript, SQL, mobile clients, or third-party integrations.
Developer examples
Use examples like this as a starting point, then adapt the timezone and precision to your application contract.
const unixSeconds = 1717243200;
const iso = new Date(unixSeconds * 1000).toISOString();
const backToUnix = Math.floor(Date.parse(iso) / 1000);Common pitfalls
The common mistake is sending an ISO string without a timezone or treating a Unix timestamp as local time. A timestamp is an instant; formatting it as local or UTC is a presentation decision.
Most timestamp bugs come from hidden assumptions: local time treated as UTC, seconds treated as milliseconds, formatted strings parsed without offsets, or narrow integer columns copied from old examples. Add tests for boundary dates and document the expected unit beside every external timestamp field.
FAQ
Which format is better for APIs?
ISO 8601 is easier to inspect, while Unix timestamps are easier to compare. Many developer APIs safely expose ISO 8601 strings and store numeric timestamps internally.
Can ISO 8601 sort correctly?
UTC ISO 8601 strings sort lexicographically when they use the same precision and timezone format. Mixed offsets should be normalized first.