Your tracking integration needs a date sanity check

#javascript #api #webdev

Every tracking integration I have seen trusts one thing it should not: that the newest event attached to a tracking number describes the shipment you are looking at.

Most of the time it does. Then a support ticket arrives saying "it says delivered in Texas in March and I ordered this in October", and you discover that a tracking number is a string in a finite format, not a permanent name for a box.

This post is the guard I wish every integration shipped with: compare the event date to the date you learned about the shipment, and refuse to surface anything that predates it.

The failure, concretely

A customer pastes a US domestic number. Your UI shows:

Delivered, In/At Mailbox — SPRING, TX — 2026-03-03 14:42

They ordered on 2026-10-09. The carrier's own website, asked about the same number on the same morning, says tracking not available.

Nothing is broken. Two different records are being shown by two systems with different retention:

The carrier's own site has moved on. USPS states on its help pages that "access to tracking information for non-signature items is limited to 120 days. Tracking information for signature items is available for 2 years."
Whatever third party showed the March delivery still has its own stored copy from back then.

So the number is live again on a new label, and the only system still holding the old story is the one that cached it.

Why your own database will do this too

If you ingest events and upsert them onto a tracking_number primary key, you have built the same cache. The second shipment's events land next to the first shipment's events, sorted by whatever you sort by, and the newest row wins the status badge. There is no field in the payload that says "different parcel".

What you do have is the moment the number entered your system. That is the anchor.

The guard

/**
 * Decide whether an event can belong to the shipment we are tracking.
 * anchor = when this tracking number entered our system (order/intake time).
 * Anything meaningfully older than the anchor belongs to a previous use
 * of the same number, or to a carrier record that has since been recycled.
 */
const STALE_DAYS = 30;

function parseEventDate(raw) {
  if (!raw) return null;
  // Carrier strings are not ISO. Cut trailing timezone notes like "[GMT+8]",
  // and normalise "2026-03-03 14:42:00" which Safari refuses as-is.
  const cleaned = String(raw).replace(/\[[^\]]*\]/g, '').trim().replace(' ', 'T');
  const d = new Date(cleaned);
  return Number.isNaN(d.getTime()) ? null : d;
}

function partitionEvents(events, anchorISO, staleDays = STALE_DAYS) {
  const anchor = new Date(anchorISO);
  const cutoff = new Date(anchor.getTime() - staleDays * 864e5);
  const current = [];
  const priorUse = [];
  for (const e of events) {
    const d = parseEventDate(e.date);
    if (d === null) { current.push(e); continue; } // unparseable: do not hide it
    (d < cutoff ? priorUse : current).push(e);
  }
  return { current, priorUse };
}

function statusFor(events, anchorISO) {
  const { current, priorUse } = partitionEvents(events, anchorISO);
  if (current.length) {
    return { status: current[0].status, stale: false };
  }
  // Everything we hold predates this shipment. Say so instead of lying.
  return {
    status: 'No scans yet for this shipment',
    stale: true,
    note: priorUse.length
      ? 'This number has older history from a previous use. It is not your parcel.'
      : null,
  };
}

Running it on the case above:

const events = [
  { date: '2026-03-03 14:42:00', status: 'Delivered, In/At Mailbox' },
  { date: '2026-03-03 10:28:00', status: 'Arrived at Post Office' },
];

statusFor(events, '2026-10-09T00:00:00Z');
// { status: 'No scans yet for this shipment',
//   stale: true,
//   note: 'This number has older history from a previous use. It is not your parcel.' }

statusFor([{ date: '2026-10-11 08:02:00', status: 'In transit' }], '2026-10-09T00:00:00Z');
// { status: 'In transit', stale: false }

Four details that bite

1. Do not hide events you failed to parse. Carrier date strings are not a standard. We have seen 2026-01-31 16:42:56 [GMT+8], bare 03/03/2026, and localised month names. If parseEventDate returns null, keep the event. A parser bug must not silently delete a customer's history — fail open, not closed.

2. Pick the anchor you actually have. Order creation time is ideal. If you only have the moment the number was first submitted to you, use that, and widen STALE_DAYS, because a buyer may paste a number days after ordering.

3. Thirty days is a deliberate overshoot. Real shipments go quiet for weeks. A cross-border parcel can sit in customs longer than anyone expects. You are not trying to catch slow parcels — you are trying to catch a delivery that happened in a different season.

4. Keep the old events, just do not promote them. Delete nothing. Partition, and render the prior-use block collapsed and labelled. The customer who sees "this number had earlier history that is not yours" stops filing a theft report.

How often is this worth coding for?

Rarer than you would guess from how loud it is. Across the tracking numbers added to our platform in the last two months, roughly one in five hundred had its newest scan dated more than two months before the number ever reached us.

That is a tiny slice. It is also, every single time, a customer who believes their parcel was delivered to a stranger in another state — which is why the ticket takes twenty minutes instead of two, and why the guard is worth the forty lines.

The one-line version

If the newest event you hold is older than the shipment itself, you are displaying somebody else's parcel. Compare the dates before you render the badge.

I work on 24hTrack, a free package tracker for 3,200+ carriers — paste any tracking number, the carrier is detected automatically, no sign-up. The measurement above comes from our own data. The USPS retention figures are from USPS's own help pages.

DEV Community