DEV Community: 24hTrack

Your tracking integration needs a date sanity check

24hTrack — Mon, 12 Oct 2026 04:34:43 +0000

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.

Why "Delivered" Is the Least Reliable Field in a Tracking API Response

24hTrack — Sun, 11 Oct 2026 04:40:01 +0000

If you consume a parcel-tracking API, the field you are most tempted to branch on is status. It is also the field most likely to be wrong about the thing your user actually cares about: whether the parcel is at their door.

This is not a data-quality problem. It is a modelling problem, and once you see it the fix is small.

One parcel, several authors

A cross-border parcel is usually carried by three different companies: the line the seller booked, the operator that moves it across the border and clears customs, and the local carrier that makes the doorstep delivery. Each one writes scans into its own system, in its own words.

When company B hands the parcel to company C, company B records an event. From B's point of view, it delivered the parcel. To its partner.

So the scan list contains a line that reads, quite literally:

Delivered to final mile carrier

...and a naive status == "Delivered" check marks the order complete while the box is sitting in a depot forty miles away.

The status field is a derived label, the scan list is the record

Most tracking APIs (ours included) expose two things:

a normalised status - a small enum like in_transit | out_for_delivery | delivered | exception
the raw events array - what each carrier actually published, with a timestamp and a location

The enum has to be produced by mapping carrier text onto buckets, and carrier text is written by whoever wrote it. "Delivered to final mile carrier", "Delivered to agent", "Delivered to service point" and "Delivered, front door" all contain the same verb and mean three different things.

The events array does not have this problem, because it carries the one field that disambiguates: location.

The disambiguation rule

For the latest event, look at the location, not the status word:

Location looks like	Meaning	UI you should render
a facility, depot, hub, airport, or another company's name	handover between carriers	still in transit
a shop, locker, access point, parcel shop	awaiting collection	action required by the customer
the recipient's own town, often with a place note (front door, porch, mailbox, neighbour)	real delivery	delivered

The middle row is the one worth special-casing. It is not in transit and it is not finished - the parcel is physically done travelling but a clock is running, because pickup points typically return a parcel to the sender after about a week. Collapsing it into delivered is how a support queue fills up with "it says delivered and my porch is empty", and collapsing it into in_transit is how a customer finds out too late.

A pragmatic implementation

You do not need NLP for this. A short rule over the latest event gets most of the way:

const HANDOVER = /(final[- ]mile|local post|delivery partner|partner carrier|tendered|transferr?ed to)/i;
const PICKUP   = /(service ?point|access ?point|parcel ?shop|pickup point|locker|post office)/i;

function refine(status, latest) {
  if (status !== 'delivered') return status;
  const text = `${latest.description} ${latest.location ?? ''}`;
  if (PICKUP.test(text))   return 'awaiting_collection';
  if (HANDOVER.test(text)) return 'in_transit';
  return 'delivered';
}

Two things that matter more than the regex itself:

Keep the raw text. If you only persist your own enum, you have thrown away the evidence and you cannot re-derive anything later when a carrier changes its wording. Store the carrier's string verbatim and normalise on read.
Do not match on "locker" or "mailbox" alone. A parcel locker owned by the recipient is a real delivery - a rule that treats every locker as a pickup point will mislabel a very large number of genuinely delivered domestic parcels. Anchor on the shop or network words instead.

That second point is not hypothetical: in a sample we checked, the single largest group of "delivered + locker" scans were ordinary residential parcel lockers, not pickup points.

The second tracking number

One more consequence of the handover. After it, the destination carrier may issue its own tracking number for the same parcel. Both are valid, both describe the same box, and neither one contains the whole journey. If your UI assumes one order has one number, that is where the trail appears to die.

If you are building this: 24hTrack (https://www.24htrack.com) is a free package tracker for 3,200+ carriers - paste any tracking number and the carrier is detected automatically, no sign-up. There is a REST API and an MCP server (npm i 24htrack-mcp) if you want an AI agent to do the lookup, and the open guides are at https://github.com/doanhnd9989/package-tracking-guide.

TL;DR

status tells you what the last company to touch the parcel thought it had finished. The events array, read with its location field, tells you where the parcel is. Branch on the second one.

Why two tracking pages disagree about the same parcel (and what it means for your integration)

24hTrack — Thu, 08 Oct 2026 05:07:06 +0000

Two tracking pages, one parcel, two different answers. A customer emails you a screenshot of a competitor's page showing a scan yours doesn't have, and asks why your order status is "behind".

I work on 24hTrack, a free multi-carrier tracking site, and this is the support ticket we get in every language. It is almost never a data bug. It is four assumptions that quietly break once a parcel crosses a border — and all four show up in code, not just in support.

1. A tracking record is a snapshot, not a feed

The carrier is the only writer. Everything downstream — your order page, your 3PL dashboard, any tracking site — is a copy of what the carrier had published at the moment that copy was made. Two copies made minutes apart can legitimately disagree.

So "their page is ahead of ours" usually means their copy is newer, not that one of you is wrong. Design your UI for that: show when you last looked, not just the status. A timestamp on the page kills more WISMO tickets than an extra status string, because it answers the question the customer is actually asking.

2. One shipment is often two numbers

This is the big one. On a cross-border order, one company carries the parcel out of the country it was posted in, and the postal carrier where the buyer lives delivers it — frequently under a second, local number the first carrier never sees.

The handover is visible in the data. On Belgian postal items we see lines like:

Export customs clearance started
Departure from office of exchange
Left from departure country/region
Arrival in the country of destination

After Arrival in the country of destination, the original number often goes quiet forever. Nothing is broken; the parcel simply stopped being that carrier's to move. If your UI treats "no new events for N days" as an exception, you will raise false alarms on every international order that is doing fine.

Model a shipment as one or more tracking legs, not one number. If you can only store one, at least don't present its silence as a failure.

3. The last two letters are the issuing country — not the destination

S10 is the UPU format: two letters, nine digits, two letters. The trailing pair identifies the postal operator that issued the number.

I have seen this used as a destination field more than once — routing a shipment to a "Belgium" bucket because the number ends in BE, when the parcel is going to Brazil. It also drives a support script that tells customers they have the wrong number.

// S10 (UPU) postal item number: 2 letters + 9 digits + 2 letters.
// The LAST two letters are the ISSUING country, not the destination.
const S10 = /^([A-Z]{2})(\d{9})([A-Z]{2})$/;

function parseS10(raw) {
  const s = String(raw).toUpperCase().replace(/[\s-]/g, '');
  const m = S10.exec(s);
  if (!m) return null;
  return { service: m[1], serial: m[2], issuedBy: m[3] };
}

Name the field issuedBy. Not country. Not destination. The name is the whole fix.

4. One carrier can have more than one number format

Length-based validation is the most common way a valid number gets rejected at the door. Canada Post publishes two formats on its own support pages: 16 digits for items delivered inside Canada, and 13 characters (S10) for items going to the US and internationally, plus prepaid envelopes and labels.

If your input accepts "a Canada Post number" as 16 digits, every prepaid-label and international customer hits an error on a number that is perfectly valid.

function looksLikeCanadaPost(raw) {
  const s = String(raw).toUpperCase().replace(/[\s-]/g, '');
  if (/^\d{16}$/.test(s)) return 'domestic-16-digit';
  const p = parseS10(s);
  if (p && p.issuedBy === 'CA') return 'international-s10';
  return null;
}

Running the two together over a mixed bag:

1111 1111 1111 1111    | s10: no                | canadaPost: domestic-16-digit
AA111111111CA          | s10: AA+9+CA           | canadaPost: international-s10
UL000000000BE          | s10: UL+9+BE           | canadaPost: no
CP000000000IE          | s10: CP+9+IE           | canadaPost: no
LX000000000NL          | s10: LX+9+NL           | canadaPost: no
1Z999AA10123456784     | s10: no                | canadaPost: no

Note the last line: a UPS-shaped number is not S10 and not Canada Post, and that is the correct answer — null, not an error.

The rule underneath all four

Shape tells you very little, and never block a lookup on it. Detection should return carrier, unknown, or ambiguous — and unknown should still run the lookup rather than throwing a validation error at the customer. A person holding a real number does not care that it failed your regex.

What to show instead

The timestamp of the last check, next to the status.
The newest line, not just a normalised status bucket. "Electronic information submitted by shipper" means the label exists and the carrier does not have the parcel yet — a completely different support action from "In transit".
An explicit note at the handover point: the final leg may be another company.

If you want to sanity-check a number against a lot of carriers without wiring anything up, you can paste it on 24hTrack — it detects the carrier from the number itself, free and without an account. There is also a REST API and an MCP server if you want this inside your own app or an AI assistant.

Numbers quoted here are medians and shares measured on our own platform, and the Canada Post formats come from Canada Post's published support pages.

Written with AI assistance. I work on 24hTrack.

Carrier names are not identifiers: 4 rules for shipping integrations

24hTrack — Wed, 07 Oct 2026 04:31:05 +0000

Every shipping integration I have seen stores a carrier field, and most of them treat it as if it were part of the shipment's identity. It is not. It is the least stable thing on the record.

Here is the evidence I keep running into, and the four design rules I would now apply from day one.

1. One carrier can have two correct names

YTO Express is 圆通速递 — Yuantong Express, based in Shanghai, listed in Shanghai and Hong Kong. "YTO" is the abbreviation it uses internationally; "Yuantong" is the English spelling of its Chinese name. Both are correct. In Australia the same operation also appears written as AU-YTO.

So carrier === "YTO Express" and carrier === "Yuantong" describe the same company, and a user searching for one will never match a record stored under the other.

This is not a Chinese-carrier quirk. It is what happens any time a company has a legal name in one language and a trading name in another, and it is extremely common in cross-border logistics.

Rule: carrier names need an alias table, and the alias table needs to be the thing you query.

// Minimal shape. The point is the normalisation, not the list.
const ALIASES = {
  ontrac:        ['ontrac', 'on trac', 'on track'],
  cainiao:       ['cainiao', 'cai niao', 'caniao'],
  straightship:  ['straightship', 'straight ship'],
  'yto-express': ['yto', 'yto express', 'yuantong', 'yuan tong', '圆通速递', 'au-yto'],
};

const norm = s => String(s ?? '')
  .toLowerCase()
  .normalize('NFKC')
  .replace(/[^\p{L}\p{N}]+/gu, ' ')   // keep CJK, drop punctuation
  .trim();

const INDEX = new Map(
  Object.entries(ALIASES).flatMap(([key, names]) => names.map(n => [norm(n), key]))
);

export const resolveCarrier = input => INDEX.get(norm(input)) ?? null;

Two details that matter more than the list itself:

\p{L} with the u flag, not \w. \w is ASCII-only, so 圆通速递 normalises to an empty string and every CJK name collapses into the same key. (We have shipped that bug. Once.)
NFKC before stripping, because full-width Latin characters turn up in labels printed by Asian systems and ＹＴＯ is not YTO under a naive comparison.

2. The carrier on the label is not always the carrier that delivers

On a cross-border route, the company the seller handed the parcel to usually hands it on again. Cainiao — Alibaba's logistics arm, the network behind most AliExpress, Taobao and Tmall orders — is explicitly a coordinating network rather than a fleet: it contracts warehouses, consolidators, airlines and local delivery companies. The parcel's last leg is done by a local carrier whose name never appeared on the original label.

If your data model has shipment.carrier as a write-once field set at ingest, you will be wrong about a large fraction of international shipments by the time they arrive.

Rule: carrier is mutable state, not an identity. Model it as "best current attribution", with a timestamp, and let it be revised.

Practically that means:

-- not this
carrier VARCHAR(40) NOT NULL  -- set once at insert

-- closer to reality
carrier          VARCHAR(40)      -- current best attribution
carrier_source   ENUM('declared','detected','reported')
carrier_updated  DATETIME

The carrier_source column earns its keep the first time a user-declared value disagrees with what the shipment itself reports. A value the user typed into a dropdown should never outrank a value that came back with the shipment's own events.

3. Number shape is a hint for some carriers and noise for others

It is tempting to build a single regex table and call carrier detection solved. The coverage is genuinely uneven, and pretending otherwise produces confident wrong answers.

Of the four carriers above, exactly one has a shape you can lean on:

Carrier	Shape	Usable as a signal?
Straightship	five letters + 13 digits, 18 chars, overwhelmingly `STRCA…`	yes — one shape dominates
OnTrac	mixed; some `D`-prefixed, many all-digit	no
YTO Express	mixed; several prefixes in regular use	no
Cainiao	mixed; may carry a partner's number entirely	no

The mechanism behind the mixed ones is always the same: large carriers absorb other networks and inherit their numbering, and cross-border legs carry partner numbers. A clean format only exists where a carrier issues every number itself.

Rule: detection returns three outcomes, not two. recognised / ambiguous / unrecognised. Collapsing ambiguous into unrecognised throws away the most useful state you have — "this looks like a real number, we just cannot attribute it" is a completely different support conversation from "this is not a tracking number".

// Three outcomes, not a boolean
{ status: 'recognised',   carrier: 'straightship', confidence: 'shape' }
{ status: 'ambiguous',    candidates: ['ontrac', 'usps'] }
{ status: 'unrecognised', reason: 'no known carrier issues this shape' }

4. Never block a lookup because the name did not match

The failure mode I see most often in support queues: a user pastes a perfectly good number, the UI asks them to pick a carrier from a dropdown, they pick the wrong one or a close-sounding one, and the lookup fails. The number was fine the whole time.

If your form has a carrier selector, make it optional and make it a filter, not a precondition. The number is the identifier. The name is a label somebody typed.

Why this adds up

The through-line is that carrier identity lives in the number, and every other representation of it — the dropdown value, the label text, the name in the order confirmation email — is a lossy copy that can go stale between ingest and delivery.

Build for that and a surprising amount of support load disappears, because the two commonest tickets ("I can't find my carrier in your list" and "your site says this number is invalid") both stop being possible.

I work on 24hTrack, a free multi-carrier package tracker — paste any tracking number, the carrier is detected automatically, no sign-up. There is also a REST API and an MCP server if you want to do this from code or from an AI assistant. The carrier facts above come from each company's own site; the shape observations come from numbers that have passed through our platform.

Validate a UPS 1Z number before you call any tracking API - the check digit is free

24hTrack — Tue, 06 Oct 2026 05:00:54 +0000

If your app accepts tracking numbers from users, you are almost certainly treating two very different failures as one. "This number does not exist" and "this number cannot exist" look identical at the API layer - both come back as not found - but only one of them is worth retrying.

UPS parcel numbers give you a way to tell them apart for free, before any network call. The last character of a 1Z number is a check digit computed from the fifteen before it.

Disclosure up front: I work on 24hTrack, a free package tracker. The numbers below come from our own data and you can reproduce the algorithm yourself in about ten lines.

The shape

A UPS parcel number is 1Z plus 16 alphanumeric characters - 18 in total, no spaces, no dashes:

1Z  999AA1  01  2345678  4
|   |       |   |        |
|   |       |   |        +-- check digit
|   |       |   +----------- package identifier
|   |       +--------------- service level
|   +-------------------------- shipper account (6 chars)
+------------------------------ fixed prefix

The shipper account being inside the number is the reason every label from a given seller opens with the same eight characters. Useful if you are grouping shipments by merchant and do not have the data to do it properly.

The check digit

export function isValidUps(tn) {
  const body = String(tn).trim().toUpperCase();
  if (!/^1Z[0-9A-Z]{16}$/.test(body)) return false;

  const chars = body.slice(2);           // 16 chars: 15 + check digit
  const check = Number(chars[15]);
  if (Number.isNaN(check)) return false;

  let total = 0;
  for (let i = 0; i < 15; i++) {
    const c = chars[i];
    // letters map to digits: A->2, B->3 ... wrapping at 10
    const v = c >= '0' && c <= '9'
      ? Number(c)
      : ((c.charCodeAt(0) - 65) % 10 + 2) % 10;
    total += i % 2 === 0 ? v : v * 2;    // alternate weighting
  }
  return (10 - (total % 10)) % 10 === check;
}

Sanity check against the number UPS uses in its own documentation examples:

isValidUps('1Z999AA10123456784'); // true
isValidUps('1Z999AA10123456785'); // false - one digit off

Does it actually hold on real traffic?

That is the part worth measuring rather than trusting. I ran this over every UPS number added to our platform in the last 60 days: 1,539 numbers, 1,539 passes, zero failures.

That is a strong enough signal to act on. If a 1Z-shaped string fails this check, it is not a parcel you have not heard about yet - it is a corrupted string.

Why this matters more than it sounds

Three things change once you can separate the two failure modes.

1. You stop retrying garbage. A tracking integration typically re-polls unknown numbers on a schedule for days. A number that fails the check digit will never resolve, so every one of those polls is wasted - against a rate limit you are probably sharing across your whole catalogue.

2. You can give the user a real error message. "We could not find that number yet, we will keep checking" is correct for a valid number with no scans. For an invalid one it is actively misleading: the customer waits instead of going back and re-copying the number. Compare:

We cannot read that number. UPS numbers are 1Z plus 16 characters, and this one does not match. Check for O typed as 0, or I typed as 1.

The four confusable pairs - 0/O, 1/I, 5/S, 8/B - are where the damage almost always is, because these numbers get read off printed labels and screenshots.

3. You validate at the edge of your system, not in the middle. This is a pure function with no I/O. It belongs in the form, not behind an HTTP call.

The important caveat

Do not use this as a carrier detector. Not every UPS parcel has a 1Z number. Economy services hand the final mile to the national postal operator and the customer is often given the postal number instead; freight shipments use a shorter, all-numeric reference; and plenty of sellers hand over an internal order code and call it a tracking number.

So the logic is one-way:

shape matches 1Z... and check digit passes -> safe to treat as a UPS parcel number
shape matches 1Z... and check digit fails -> reject at the form, do not queue it
shape does not match -> say nothing about UPS; it may still be a perfectly good number belonging to someone else

That last branch is the one most implementations get wrong. "Not a 1Z number" means "I have no opinion", not "invalid".

If you would rather not maintain shape rules at all

Carrier-shape detection is a surprisingly long tail - a few hundred patterns, several of them shared between companies, plus the re-labelling that happens when a cross-border parcel is handed to a local carrier. We ended up building that detection anyway, so it is exposed: paste any number into 24hTrack and the carrier is identified for you, free and without an account, or call it from code through the REST API. There is also an MCP server if you want an AI agent to do it.

But if all you need is to stop queueing broken UPS numbers, the ten lines above will do it today.

Validate tracking numbers at ingest, not at the support desk

24hTrack — Mon, 05 Oct 2026 05:28:58 +0000

Full disclosure: I work on 24hTrack, a free multi-carrier package tracker. The patterns below come from running that ingest path; discount the last section accordingly.

Most shipment pipelines validate a tracking number exactly once: when a customer complains that it does not work. By then the number has already been written to the order, emailed to the buyer, and copied into three systems.

Treat it as untrusted input at ingest, the way you already treat an email address.

A tracking number has three validation outcomes, not two

The usual model is valid | invalid. Real carrier identification is a classifier with three outcomes, and conflating two of them is where the bugs live:

Recognised - the shape matches exactly one carrier's published format.
Ambiguous - the shape matches more than one. Bare numeric formats do this constantly: a 12-digit string is FedEx Express or a dozen regional couriers. "2 letters + 9 digits + 2 letters" is any UPU member postal operator; only the trailing country code narrows it.
Unrecognised - matches nothing published anywhere.

Outcome 3 is the one worth acting on at ingest, because it is almost never a carrier problem. It is a warehouse job code, a consolidator reference, or an order ID that someone pasted into the wrong column. Catching it on day zero costs one validation call. Catching it on day twelve costs a support ticket and a refund window.

Check digits are free validation and almost nobody uses them

Several formats carry a check digit you can verify offline, with no API call:

USPS IMpb (20-22 digits): mod-10 with alternating 3/1 weights.
FedEx Express (12 digits): mod-11 with weights 1,3,7 repeating.
UPU S10 (XX123456789YY): mod-11 on the 8 serial digits, with 5 and 0 as special cases.

// USPS IMpb mod-10, weights alternating 3 and 1 from the right
function uspsCheckDigitOk(tn) {
  const d = tn.replace(/\D/g, '');
  if (d.length < 20 || d.length > 22) return false;
  const body = d.slice(0, -1), check = Number(d.slice(-1));
  let sum = 0;
  for (let i = body.length - 1, w = 3; i >= 0; i--, w = w === 3 ? 1 : 3) {
    sum += Number(body[i]) * w;
  }
  return (10 - (sum % 10)) % 10 === check;
}

A failed check digit on a well-formed-looking number is nearly always a transcription error - a digit dropped, two swapped. That is a different support reply from "the carrier has not scanned it yet", and your system is the only thing that can tell them apart.

One warning from experience: calibrate a check-digit rule against your own historical data before you ship it as a hard reject. We tightened a USPS rule once that looked obviously correct and would have quietly orphaned a slice of real numbers that a partner was formatting slightly differently. Run it in log-only mode first and count what it would have rejected.

Carrier is a mutable field. Model it that way

A surprising number of schemas store carrier as if it were decided once, at creation. It is not:

Parcels get re-labelled mid-journey. Purolator even has a public status for it - New Tracking Number Assigned - at which point the original number stops moving and a different one carries the rest of the trip.
Consolidators issue their own job number first and a real carrier number later.
Rebrands happen. Toll Global Express became Team Global Express in 2022 and the old portal is gone, but the numbers on the labels did not change.

Store (carrier_code, number) and resolve the tracking URL at render time. Never persist a tracking URL - it is derived data with a shorter lifetime than the row it lives on.

"Reference" is not a key, even when the carrier accepts it

Some carriers deliberately accept the shipper's own code. Purolator's tracking box asks for "a PIN or Reference", where a Reference is up to 15 characters chosen by whoever shipped it.

That is useful for humans and dangerous for code. A reference is not unique across shippers: two merchants can both use INV-1042. If you let a reference into the same column as a carrier number, you have introduced a lookup that can return somebody else's shipment. Keep a separate shipper_reference column and never make it the join key.

The same applies to naming. Several carriers do not use the phrase "tracking number" at all: Purolator says PIN, US LTL freight says PRO, air cargo says AWB (a 3-digit airline prefix plus 8 digits), Australian freight says consignment note. If you render a generic "Tracking number" label, a chunk of your users will be looking for something they cannot find on the carrier's site either.

Two different timeouts, two different alerts

Teams usually have one staleness alert: no movement for N days. You want two, because the remedies are unrelated.

Condition	What it means	Who fixes it
Zero scans ever, N days after ingest	the number may not exist in any carrier system	you and the merchant - data problem
Had scans, none for N days	the parcel is between scan points	nobody, usually - it is in the air, in customs, or mid-handover

The second is normal and should be scored against that lane's own distribution, not a global constant. Cross-border parcels average roughly 18-22 scans end to end against 4-5 for a domestic one, and a lane with a median of 13 days can have an 80th percentile near 29. A flat "two weeks means lost" rule will fire on more than one parcel in five that is behaving perfectly.

The first is the one that actually needs a human, and it is the one almost nobody alerts on.

The one-line version

Validate shape at ingest, verify check digits where the carrier publishes one, keep carrier mutable, keep shipper references out of your key, and alert separately on "never scanned" versus "not scanned lately".

If you want a reference implementation to compare against, 24hTrack does the detection step for 3,200+ carriers from the number alone, with a REST API and an MCP server if you want an AI assistant to do the lookup. Free to try without an account.

Your tracking integration probably can't tell a refusal from a failed delivery - and on COD orders that matters

24hTrack — Sun, 04 Oct 2026 05:55:43 +0000

Disclosure: I work on 24hTrack, a multi-carrier package tracker. The patterns below apply whatever you build on.

Most post-purchase code treats a shipment as a line that moves one way: label created, in transit, out for delivery, delivered. That model is fine until the order is cash on delivery, and then it quietly produces wrong answers for a large part of the world.

Cash on delivery is ordinary across the Gulf, much of Africa and a lot of South-East Asia. GFS Express, one of the networks carrying Chinese e-commerce into that region, lists local operations in Saudi Arabia, Bahrain, Jordan, Kuwait, Oman, Qatar, Azerbaijan, Georgia and South Africa, and sells cash collection to merchants as a product with weekly remittance. If your buyers are there, a meaningful share of your orders are only paid for at the doorstep.

Four things that break.

1. "Delivered" stops meaning "paid"

On a prepaid order those two collapse into one event. On COD they are different facts arriving from different systems: the scan from the carrier, the money from a remittance file days later. If your fulfilment logic recognises revenue on a delivery scan, COD will overstate it, and every refusal becomes a correction you have to find by hand.

2. The reverse path is a normal path, not an error

A COD buyer can simply decline at the door. Tracking records that as a failed attempt and then a return - the same two statuses you get when nobody was home. Carriers rarely tell you which it was. If your code treats returned as an exception to alert on, COD markets will drown you in alerts for transactions that worked exactly as designed. Model it as an outcome with a reason you may never learn, not as a failure.

3. Amounts are not in tracking data, and you should not synthesise them

Carriers publish scans: a status, a time, often a place. They do not publish what the recipient owes. Every so often someone asks us to show the COD amount on a tracking page. We can't, and neither can anyone else reading the same feeds - the number lives in the order, not in the shipment. If your UI implies otherwise, you have invented a figure a customer will act on.

4. Duty is a second, unrelated money event

Import duty and VAT are billed by the carrier or the post, usually ahead of delivery, usually by SMS or email with a link. It can land on a fully prepaid order. It is not COD and it is not collected the same way. Conflating them produces support answers that are confidently wrong.

Where the wrong answers actually surface

Not in your dashboard - in the "is this a scam?" ticket. Buyers in COD markets are also the buyers most targeted by doorstep payment fraud, and they cannot tell your legitimate collection apart from it. The cheap mitigation is boring and entirely on your side: state the COD amount in the order confirmation, in the buyer's currency, in a line they can find on a phone at the door. Everything a scammer cannot replicate - a matching order, a receipt, payment to the courier rather than a link - then becomes checkable in ten seconds.

A small data detail while you are in there

When you normalise scans, do not assume the location is a field. Several carriers write it into the text:

Riyadh, Parcel picked up from customs

If you render a location column from event.location alone, those rows look placeless, and your "we have no location for this parcel" branch fires on a parcel whose city is sitting in the first eight characters of the description. Read the words before you declare the field empty.

None of this needs a new vendor. It needs the shipment model to have two axes - where the goods are, and whether the money moved - instead of one.

If you would rather not build the tracking half: 24hTrack detects the carrier from the number across 3,200+ carriers, is free on the web with no sign-up, syncs to Google Sheets at no cost, and has a REST API plus an MCP server (npm i 24htrack-mcp) for AI agents. The open guide and transit-time data are on GitHub.

FAQ

Can a tracking API tell me the cash-on-delivery amount?
No. Tracking feeds carry statuses, timestamps and sometimes locations. The amount lives in the order record, not in the shipment, so any tracking tool showing you a figure is reading it from somewhere other than the carrier.

How do I distinguish a refused COD parcel from a missed delivery?
Usually you cannot from the scans alone - both appear as a failed attempt followed by a return. Carry your own signal instead: a COD flag on the order plus the remittance file, and treat an unpaid return on a COD order as a refusal until proven otherwise.

Is cash on delivery the same as paying customs duty?
No. COD is the price of the goods, collected for the seller. Duty is tax, billed by the carrier or post, and it can appear on an order that was already paid in full.

Which carriers use cash on delivery?
It is a service sold to merchants rather than a property of a carrier, and it is common wherever the market expects it. GFS Express is one example that advertises collection with weekly payout to the seller.

Don't store a tracking URL. Store the number and resolve the link at render time.

24hTrack — Sat, 03 Oct 2026 05:18:58 +0000

Most order systems I have looked at store a tracking URL on the shipment: a full link, built at order creation, pasted into the confirmation email and the order page.

That link is a liability, and the failure mode is quiet. Here is the one that bit us this week.

The failure

Toll Group sold its Global Express division to Allegro Funds, and the business has traded as Team Global Express since 2022. The domestic parcel arm is still IPEC. The customer portal moved from MyToll to myteamge.com.

Checked on 3 October 2026: mytoll.com and www.mytoll.com return no page at all. Not a 404 page, not a redirect - the connection does not complete.

So every order record that baked in a MyToll URL now ships a dead link to the customer. The parcel is fine. The number was never reissued and still resolves on the new portal. The only thing that broke is a string written down two years ago.

Why storing the URL is the bug

A tracking URL is derived data. It is a function of (carrier, number) evaluated at one point in time. Storing it freezes that evaluation forever, and the inputs keep moving:

Rebrands and acquisitions. Toll Global Express to Team Global Express (2022). CIRRO E-Commerce was founded as PARCLL, renamed April 2023, acquired by GOFO February 2026.
Last-mile handover. A cross-border parcel is handed to a domestic carrier near the end, so the right link to show changes mid-journey.
Portal path changes. Carriers restructure query params without warning, and a stored URL with the old param silently renders an empty result.

Store the facts, derive the view:

// not this
shipment.tracking_url = "https://www.mytoll.com/?searchQuery=" + number

// this
shipment.carrier_code    = "TEAM_GLOBAL_EXPRESS"  // mutable
shipment.tracking_number = "64................001" // immutable
// at render time:
trackingUrl(shipment.carrier_code, shipment.tracking_number)

Now a rebrand is a one-line change in a lookup table, not a backfill across every historical order.

Carrier is a mutable field, not a constant

The second half of the same bug: most schemas write carrier once, at order creation, from the shipping method the customer picked. It then never changes, even when the parcel changes hands.

Make it updatable, and normalise it. One Australian shipment can reach you labelled Toll, Toll IPEC, Toll Road Express or Team Global Express, depending on which system passed the data along. If you report on carrier performance without collapsing those into one key, you are reporting on four carriers that do not exist.

TOLL | TOLL IPEC | TOLL ROAD EXPRESS | TEAM GLOBAL EXPRESS  ->  TEAM_GLOBAL_EXPRESS
PARCLL | CIRRO E-COMMERCE                                   ->  CIRRO_ECOMMERCE

Keep the raw string the partner sent you in a separate column. You will want it the first time a new spelling appears.

Three things worth doing today

Grep your templates, help articles and support macros for carrier names, not just URLs. The name is what a customer types into a search engine when your link fails, and a dead brand name sends them nowhere.
Add a cheap liveness check on the carrier URLs you emit. A weekly job that requests each distinct base URL and alerts on connection failure would have caught MyToll the week it went dark. Do not check for HTTP 200 only - a carrier that serves a styled "no results" page at 200 is also broken for your customer.
Do not derive a carrier from number length alone. Team Global Express numbers are 22 digits beginning 64: a four-digit prefix, a thirteen-digit consignment number, then a three-digit item sequence. Several US numeric labels are also 20-22 digits. Anchor on prefix and length together, and measure a rule against real data before you ship it.

The customer-facing half

If the link does fail, the person holding the parcel has one workable move: search the brand together with "renamed" or "acquired", or paste the number into a universal tracker that works the carrier out from the number itself rather than from a stored name. We build one - 24hTrack is a free package tracker for 3,200+ carriers; paste any tracking number, the carrier is detected automatically, no sign-up. A rename never invalidates the number, so it still resolves.

Written by the team at 24hTrack. Longer walkthrough of the Toll case, with the dates and the number format: https://youtu.be/kbCsSWW4d6k

Two couriers, one name: why you should key a tracking integration on number shape, not carrier name

24hTrack — Fri, 02 Oct 2026 04:41:42 +0000

If you are building anything that touches shipment tracking - an order page, a WISMO deflection flow, a 3PL dashboard - there is a failure mode that does not show up in your tests and shows up constantly in production: two different courier companies with the same name.

Not similar. The same.

CTT is the Portuguese post (ctt.pt).
CTT Express is a Spanish courier (cttexpress.com).

Different companies, different networks, different tracking systems. A consignment number issued by one is simply not recognised by the other. If your integration stores carrier: "CTT" as a string and later resolves that string to a tracking URL, you have a coin flip baked into your data model, and the half that loses sends a customer to a page that says their parcel does not exist.

It is not a rare shape either. Shippers reuse initialisms heavily: three-letter brands, "Express" suffixes, and local operators that took a name already in use somewhere else. On top of that, a generic word collision is just as damaging for discovery: "247Express" is a real Vietnamese courier operating since 2005, but the string 247 tracking reads to a search engine as round-the-clock tracking, so users looking for the company and users looking for the concept land in the same bucket.

Here is what I would do differently, having watched this break.

1. The number is evidence. The name is a label somebody typed.

The carrier name on an order usually arrives from one of three places: a dropdown the merchant picked, a shipping method chosen at checkout, or free text in a CSV. None of those is authoritative about who is physically carrying the box. The tracking number, by contrast, is issued by the carrier's own system and carries its format.

So resolve carrier from the number pattern first, and treat any stored name as a hint to be overridden - not the other way around.

resolveCarrier(order):
  byShape = matchPattern(order.trackingNumber)   # authoritative
  if byShape: return byShape
  return normalise(order.carrierName)            # fallback, not truth

The practical payoff: when a merchant types "CTT" and the number is clearly a Spanish CTT Express pattern, you route correctly anyway.

2. Anchor patterns on prefix and length, or you will cannibalise

The tempting rule is a loose one. It is also the one that quietly steals other carriers' parcels:

# Don't
/^\d{12}$/            -> "FedEx"
/^[A-Z]{3}\d+[A-Z]{2}$/ -> "SomeCarrier"

A bare twelve digits is not a carrier. It is a length. Several operators issue twelve-digit numbers, and the moment your rule claims them, their parcels get routed to the wrong tracking system and fail - silently, because a failed lookup looks identical to "no data yet".

Anchor both ends:

# Do
/^JCZ\d{10}[A-Z]{2}$/   # prefix + exact digit count + suffix class

And before you add a rule, run it against your whole existing corpus and count how many numbers it takes away from a rule that already works. If a new rule rescues 30 unidentified numbers but overrides 120 already-correct ones, it is a regression wearing a feature's clothes. Measure rescue vs clobber, not just precision on the happy path.

3. Do not publish a format you have not measured

If you show users "your number looks like XXX", that string had better be true, because people use it to decide whether a number is even the right one.

The rule I settled on: only state a format when a single shape accounts for 60% or more of that carrier's numbers in your sample, and say so in the shape, not with a real number. Below that, say nothing. One carrier I looked at recently had a dominant shape at 91% - safe to print. Another had its most common shape at 57%, with the rest of the basket carrying other carriers' prefixes entirely, because merchants had been filing anything into that carrier field. "Eleven digits" would have been a guess dressed as a fact.

The honest answer, when the data is mixed, is to say nothing about the format and let the number resolve itself.

4. Never use a real tracking number as the example

Obvious when written down, routinely violated in docs and UI copy. A real number identifies a real shipment to a real address, and once it is in your public docs it is in search results.

Publish the shape:

Three letters, ten digits, two letters (e.g. ABC0000000000XX)

not someone's parcel.

5. Carrier must be a correctable field, not a derived constant

The last one, and the one that bites cross-border integrations hardest: the company that finally delivers is frequently not the company named at checkout. Cross-border shippers typically carry the parcel out of the origin country and hand the final leg to a local courier or post. That means the correct carrier value for an order can legitimately change after the order record was written, and one shipment can legitimately hold more than one number.

If carrier is computed once at insert time and never revisited, every one of those orders ends its life displaying a timeline that stopped a week ago, and your support queue fills with people who think the parcel is lost. It is not. The page ended; the parcel moved on under a different name.

The summary, if you only take one thing: names are ambiguous, user-supplied and mutable; number patterns are issued by the system that actually has the parcel. Key on the pattern, keep the name as a correctable hint, and only publish a format you have counted.

I work at 24hTrack, a free package tracker that identifies the carrier from the number across 3,200+ carriers - which is exactly why these collisions are my problem rather than a trivia question. Written with AI assistance.

Don't localize carrier scan timestamps. You are not storing an instant.

24hTrack — Thu, 01 Oct 2026 06:42:11 +0000

If you build order-tracking UI, you have almost certainly done this:

new Date(scan.timestamp).toLocaleString()

It looks correct. It is the single most common way tracking pages end up lying to customers, and the bug report you get back will not look like a timezone bug. It will look like this, which is a real support message we got this week:

"This morning my package said delivered at 21:49. This was at 6:04 am. It was not delivered to my house."

Two different complaints are tangled together there, and only one of them is the carrier's fault.

A scan is a local wall-clock reading, not an instant

A tracking event is produced by a device in a facility, or in a driver's hand, writing down the time where the scan happened. Carriers publish that wall-clock reading. Most of them do not publish an offset with it.

So the string 2026-09-30 21:49:00 arriving in your pipeline is not an instant in time. It is "the clock on the wall at whichever building scanned this said 21:49". Without the offset you cannot convert it, and if you treat it as UTC and then render it in the viewer's zone, you have invented a number nobody published.

The failure mode is nasty because it is plausible. Attach Z to a naive string, render in the browser's zone, and a 09:57 delivery in Germany becomes 16:57 for a viewer in Vietnam. Nothing throws. The page just shows a time that never existed, and the customer - who was standing in their hallway at 09:57 - concludes your tracking is broken.

What we do instead

We print the digits the carrier published, unconverted:

// The stored value is the carrier's wall clock with no offset.
// Reading it back with UTC getters returns the original digits unchanged.
const dt = new Date(value)
return `${dt.getUTCFullYear()}-${pad2(dt.getUTCMonth() + 1)}-${pad2(dt.getUTCDate())} `
     + `${pad2(dt.getUTCHours())}:${pad2(dt.getUTCMinutes())}`

Using UTC getters on a value you only ever tagged as UTC is not a hack, it is the inverse of the tag. You get back exactly what the carrier said. The rule that follows:

Never convert a timestamp whose offset you were never given. Render it as text and label whose clock it is.

If you do have a genuine offset - some carriers send one, and your own events like "we last checked this" are real instants - convert those freely. Just keep the two classes apart in your schema. One is an instant. The other is a string that looks like one.

Then handle the scans that have no clock at all

Once you stop converting, you notice the second problem: not every scan has a time.

Measured on delivery scans flowing through our platform (sample of ~27,000 recent delivery events):

	share
carries a time of day	~96%
date only, no clock	~4%

Four percent sounds small until it is the one parcel a customer is angry about. Those arrive as 09/18/2026 with nothing after it. new Date() will happily give you midnight, your formatter will print 00:00, and you have just told someone their parcel was delivered at midnight.

// Treat "no clock" as a distinct state. Do not let a parser invent 00:00.
const HAS_CLOCK = /\d{1,2}:\d{2}/
if (!HAS_CLOCK.test(raw)) return { date: parseDateOnly(raw), time: null }

Render that as the date alone. A missing time is information: it tells the customer the carrier never published a minute, so there is no minute to argue about.

Watch the format spread while you are in there. In the same sample the clock-bearing values came in at least two shapes - YYYY-MM-DD HH:MM:SS and July 20, 2026 9:00 PM. If you regex for one, you will silently classify the other as "no time". I did exactly that in the first pass of this measurement and got 72% instead of 96%; the 12-hour strings were hiding in the remainder.

Do not build "is this late?" on the hour either

The last trap: once you have hours, it is tempting to flag odd ones. Resist.

Delivery scans in that same sample, by hour of day (carrier local):

Busiest window is late morning to mid-afternoon, roughly 8-9% of deliveries per hour
Between 20:00 and 05:59: about 9%, or roughly 1 in 11

A 21:49 delivery scan is not an anomaly worth surfacing as one. Contract and gig drivers finish the route they were assigned, and in peak season that runs later. If your UI puts a warning badge on evening deliveries, you will generate support tickets for one parcel in eleven, every day, forever.

The part that actually helps the customer

Having removed three ways to be wrong, here is the one field worth promoting in the UI: the location on the delivery scan, not the minute.

"Delivered" with the customer's town on it is a different claim from "Delivered" at a depot, a locker, or an access point. That distinction tells the customer whether to look on their porch or to go ask the seller to open an investigation. The timestamp, converted or not, never tells them that.

So: store the offset-less string as a string, label whose clock it is, treat "no clock" as its own state, don't badge evening deliveries, and put the scan location where the eye lands first.

I work on 24hTrack (24htrack.com), a free package tracker for 3,200+ carriers - paste any tracking number, the carrier is detected automatically, no sign-up. The percentages above come from delivery scans on our own platform. There is a longer, non-technical version of this as an open guide (CC BY).

Translating carrier scan text: all-or-nothing, or don't bother

24hTrack — Wed, 30 Sep 2026 05:19:19 +0000

Every cross-border tracking UI eventually hits the same wall: a scan line arrives in a language your users cannot read, and you have to decide what to render.

邮件离开处理中心【广州】
已妥投【US California Olivehurst 95961】
包裹已签收，如有疑问请联系收件人

The naive fix is a phrase dictionary plus str.replace. That is the right idea and the wrong implementation, and the failure modes are specific enough to be worth writing down. Everything below came out of shipping this on a live corpus of Chinese-language scan lines.

1. A half-translated sentence is worse than an untranslated one

This is the rule that decides the whole design.

包裹已签收，如有疑问请联系收件人 contains a phrase you probably have in your dictionary (已签收 = delivered, signed for) and a clause you probably do not (if you have questions, contact the recipient). Replace the part you know and the user gets:

Delivered (signed for)，如有疑问请联系收件人

That reads as broken software, not as foreign text. Worse, it hides which half you actually understood — the untouched half might be an instruction the user needs to act on.

So: translate all of it, or hand back the original byte for byte.

function gloss(text) {
  let out = text
  for (const [re, en] of PHRASES) out = out.replace(re, ` ${en} `)
  if (out === text) return text            // recognised nothing: unchanged
  if (PROSE_RE.test(strip(out))) return text  // real prose survived: give up
  return tidy(out)
}

2. You need a boundary between "place name" and "sentence"

The all-or-nothing check needs to answer: is what's left a proper noun, or a clause I failed to read?

Chinese does not put spaces between words, so you cannot count tokens. What works is a character-run threshold. Measured against real place names and real clauses:

东莞市 (Dongguan City) — 3 characters
深圳 (Shenzhen) — 2
如有疑问请联系收件人 — 10

Four is the boundary. A run of 4+ Han characters is a clause; shorter is a name.

const PROSE_RE = /[぀-ヿ一-鿿가-힯]{4,}/

And strip bracketed payloads before testing, because carriers put the location inside 【…】 and you deliberately never translate those:

const strip = s => s.replace(/【[^】]*】/g, '')

3. Ordering is load-bearing, and getting it wrong is silent

Dictionary entries overlap. 邮件离开处理中心 contains 离开处理中心 contains 离开. Put the short one first and the long one can never match:

邮件到达处理中心【SZ】
  → 邮件 Arrived at sorting centre 【SZ】   // orphan characters, prose gate trips, whole row reverts

When we put the bare forms first by accident, it made thousands of rows worse — and nothing threw. The output was just slightly wrong on a page nobody was diffing.

Two habits that catch this:

Longest-prefix first, enforced by a test that asserts entry order, not just entry presence.
Diff old vs new over your whole live corpus before shipping, and count three things: rows changed, rows emptied, rows that lost more than half their length. "Rows emptied" should be zero, always.

4. Never gloss a bare noun

We had a 处理中心 → "sorting centre" entry. It reached inside a facility name:

【深圳邮区中心邮件处理中心】  →  【深圳邮区中心邮件 sorting centre】

Every entry should be a verb plus its object, or a pattern that consumes the brackets:

[/离开(【[^】]{0,40}】)处理中心/g, 'Departed $1 sorting centre'],
[/到达(【[^】]{0,40}】)处理中心/g, 'Arrived at $1 sorting centre'],

5. Pad your replacements, then collapse

No spaces between words means a replacement welds itself to whatever follows:

邮件离开处理中心Dongguan  →  Departed sorting centreDongguan

Pad both sides on insert, then collapse runs and trim before punctuation:

out.replace(/\s*，\s*/g, ', ')
   .replace(/\s{2,}/g, ' ')
   .replace(/\s+([,.;:)\]】])/g, '$1')
   .trim()

Note the full-width comma ， — leave it in and you get Chinese punctuation inside English sentences.

6. Do this on the read path only

The glossed string is for display. The stored value stays exactly as the carrier sent it.

That is not tidiness. Anything derived from status text — a delivered_at stamp, a downgrade guard, a "stop polling this parcel" rule — must key off the carrier's own words. Translate on write and you have quietly made your business logic depend on the current contents of a phrase table. Change the table, change the meaning of historical rows.

One function, called from every render surface. No new call sites.

The short version

All-or-nothing: fully translated, or byte-identical.
4+ CJK characters in a row means a clause, not a name — bail out.
Longest phrase first, and test the ordering.
Verb + object, never a bare noun.
Pad on insert, collapse after.
Display layer only; never the write path.

If you want to see the output rather than the code: 24hTrack is a free package tracker for 3,200+ carriers — paste any tracking number, the carrier is detected automatically, no sign-up — and the recognised Chinese scan lines are rendered in English on the timeline. There is a plain-English walkthrough of the phrases themselves here.

Written with AI assistance; the measurements and the failure cases are from our own production corpus.

Stop showing "last updated 5 days ago" on order tracking - classify the scan instead

24hTrack — Tue, 29 Sep 2026 04:45:30 +0000

If you build order-status pages, there is a good chance you render something like Last updated 5 days ago and let the customer decide what it means. They decide it means the parcel is lost, and they open a ticket.

Elapsed time is close to useless as a signal on a tracking timeline, because a tracking feed is not a location stream. It is an append-only log of handling events. A row appears only when a human or a machine physically scans the barcode. Between scans the parcel is moving and nothing is written. So "no event for five days" is not an error state - on some legs it is the expected state.

The signal you actually have

The useful signal is the type and place of the most recent event, not its age. Roughly five classes cover almost everything you will see:

Class	Typical wording	Is silence expected?
`ORIGIN_DEPARTED`	departed, left facility, handed to airline	Yes - longest gaps in the journey
`IMPORT_PENDING`	arrived at destination country, import scan, customs clearance	Yes, unless duties or documents were requested
`DOMESTIC_HUB`	arrived at a depot or sorting centre in the destination country	No - short leg remaining
`HANDOVER`	handed over to local partner, transferred to another carrier	Yes, permanently - this carrier stops publishing
`NO_SCAN`	nothing at all	Depends how long since the label was created

Once you have that, the copy writes itself, and it is different copy per class rather than one "still on its way" for everything.

// deliberately boring: substring rules over a normalised string
const classify = (ev, destCountry) => {
  const s = (ev.description || '').toLowerCase()
  if (/handed over|transferred to|local partner/.test(s)) return 'HANDOVER'
  if (/customs|import|arrived at destination country/.test(s)) return 'IMPORT_PENDING'
  if (/departed|left .*facility|handed to airline/.test(s)
      && ev.country !== destCountry) return 'ORIGIN_DEPARTED'
  if (ev.country === destCountry) return 'DOMESTIC_HUB'
  return 'IN_TRANSIT'
}

const shouldEscalate = (last, now, destCountry) => {
  const cls = classify(last, destCountry)
  const days = (now - new Date(last.at)) / 864e5
  if (cls === 'IMPORT_PENDING') return last.dutiesRequested === true
  if (cls === 'DOMESTIC_HUB')   return days > 7   // short leg: a week is odd
  if (cls === 'HANDOVER')       return false      // track the second carrier
  return days > 21                                // cross-border linehaul
}

Two things worth building in beyond the table.

A handover is a terminal state for that carrier, not a pause. Once a parcel is handed to a last-mile partner, the original carrier will never add another row. If your UI polls only the primary carrier, it will show "no update" forever while the parcel is being delivered under a different number. Model handover as its own visible state and, where you can, follow the second leg.

Distinguish "no scan yet" from "scans stopped". A number that has never had a single event is usually a label that was printed but not handed over - or a customer pasting an order number instead of a tracking number. That is a different email from a parcel that moved and then went quiet, and conflating them is where a lot of support looping comes from.

Why this cuts tickets

The question behind almost every where-is-my-order contact is not "where is it" but "is something wrong, and do I need to do something". A status line that answers that directly - waiting is correct here, or this one needs you to pay duties, or this is worth chasing - resolves the contact before it is made. Last updated 5 days ago answers none of it.

If you want to see what a real timeline looks like across both legs, 24hTrack is free and needs no sign-up: paste a number and the carrier is detected automatically, across 3,200+ carriers. There is also a REST API and an MCP server if you would rather pull events into your own UI, and an open guide repo with status wordings and number formats: https://github.com/doanhnd9989/package-tracking-guide

Written by the team at 24hTrack, with AI assistance.