Tracking API timestamps when the event timezone is unknown

Treat UTC and source-local timestamps as different types

When the timezone is verifiable, events[].timestamp is a UTC ISO 8601 value. When it is not, timestamp is null and the event can include timestamp_local, timestamp_timezone: unknown and timestamp_precision. The local value is source text with its date/time precision; it is not an implicit timezone in your deployment environment.

For example, 2026-10-13T09:30:00 without an offset could describe different instants in different regions. Even a place name is not a complete timezone contract. The source’s context and daylight-saving rules matter, and guessing from a destination country can shift a scan by hours.

Make the limitation visible in the parcel timeline

A timeline can preserve the scan’s meaning without inventing its time. Show the description, location when supplied, and a local-time label for unknown-zone events. Avoid placing those rows on a globally precise UTC chart, especially when a parcel changes carrier or crosses borders.

The helper below performs UTC formatting only on a validated timestamp with an explicit UTC suffix. It leaves timestamp_local unchanged except for replacing the separator for readability. Never convert a local-only value through new Date merely because the API retained a valid calendar date.

function scanTimeLabel(event) {
  if (typeof event.timestamp === 'string' &&
      event.timestamp.endsWith('Z') &&
      Number.isFinite(Date.parse(event.timestamp))) {
    return new Intl.DateTimeFormat('en-GB', {
      dateStyle: 'medium', timeStyle: 'short', timeZone: 'UTC'
    }).format(new Date(event.timestamp)) + ' UTC';
  }
  if (event.timestamp === null && event.timestamp_local &&
      event.timestamp_timezone === 'unknown') {
    return event.timestamp_local.replace('T', ' ') +
      ' — timezone not supplied';
  }
  return 'Scan time unavailable';
}

Preserve history order instead of sorting guessed times

An unknown local time cannot be compared safely with an instant in another timezone. Preserve the supplied source history order where UTC chronology is unavailable. If your projection stores receipt time, use it as observation order and label it accordingly; it is still not the carrier scan’s instant.

For example, a supplier’s origin scan at 09:00 and a last-mile scan at 08:30 do not establish reverse movement. They may have different offsets, or the source may publish them later. A consumer that sorts guessed local timestamps can make a real parcel history appear contradictory.

Keep original values and timezone evidence in storage. A later provider update that adds a verified offset can be represented as new evidence without silently rewriting the meaning of an earlier observation.

Do not infer a stall from unknown scan instants

Trace’s no-recent-scan alert requires a successful verified observation and UTC instants for every scan, then checks the configured stalled_after_hours threshold. Failed or stale lookups and unknown-zone histories do not establish a stall. A carrier-reported exception is a separate fact with its own scan wording.

If your support workflow needs a rule for unknown-zone histories, name it as your own policy and document its limitations. For example, ‘No fresh verified lookup for two days’ measures an observation gap, not ‘The parcel has not moved for two days.’ Those statements support different investigations.

Report duration exclusions alongside the result

Trace merchant duration metrics use eligible verified UTC transit and delivered scans. Unknown-timezone and incomplete histories are excluded, and the response discloses duration sample counts and exclusions. A median without its denominator can hide the routes with the least evidence.

Keep order purchase time, fulfillment time, scan time and observation time separate. An observed transit duration is not purchase-to-delivery duration, an SLA or proof that one carrier caused a delay. Compare cohorts only after checking eligibility and missing-data patterns.

• Test unknown local times and valid UTC timestamps with the sandbox endpoint.
• Include a malformed timestamp in your UI tests so it cannot silently format as a real date.
• Test carrier handoffs and histories containing both known and unknown timezones.
• Show eligible sample counts and exclusions when displaying duration analytics.
• Keep support wording explicit about whether a condition is reported by a carrier or inferred by your application.

Common questions

References & next steps

Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.

• Trace timestamp field contract
• Trace no-scan alert conditions
• Trace analytics eligibility rules