Overview
Unix time is traditionally seconds, but JavaScript Date values use milliseconds. Current seconds timestamps are usually 10 digits, while current millisecond timestamps are usually 13 digits. Confusing the two creates dates in 1970 or dates far in the future.
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 seconds for Unix CLI tools, many databases, and compact API fields. Use milliseconds for JavaScript Date, browser events, and APIs that explicitly document millisecond precision.
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 seconds = 1717243200;
const milliseconds = seconds * 1000;
const date = new Date(milliseconds);Common pitfalls
Digit length is a useful clue, not a contract. Always document field units with names like created_at_unix_seconds or createdAtMs.
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
Why does JavaScript need * 1000?
JavaScript Date expects milliseconds since the Unix epoch, while Unix timestamps are commonly seconds.
Are 13-digit timestamps always milliseconds?
Usually for current dates, but APIs should still document the unit explicitly.