A tracking number can be valid and never scan: the third state your order lookup is missing
If you build order lookups, you have almost certainly modelled tracking as two states: we have a number and we have scans. That model produces a specific, recurring bug report - "the number is right but your page shows n
If you build order lookups, you have almost certainly modelled tracking as two states: we have a number and we have scans. That model produces a specific, recurring bug report - "the number is right but your page shows nothing" - and the bug is usually not in your code.
There is a third state in between, and it is where a lot of cross-border shipments live.
Three states, not two
- Number issued. A seller generates a consignment number from the carrier's system. It is syntactically valid and will pass any format check you write.
- Goods booked in. Something physical arrives at a warehouse and a barcode is read. This is where the first scan is born - not at checkout, not when the label is printed.
- Moving. Scans accumulate.
Most lookup UIs collapse 1 and 2. So a shipment sitting in state 1 renders exactly like a failed lookup, and your support queue fills with people who were told their number was wrong when it was fine.
Why state 1 persists longer than you would expect
Cross-border parcels are rarely carried end to end by one company. They typically start with a consolidator that gathers, exports, flies, clears, and then hands the parcel to a delivery company in the destination country. Consolidators suspend lanes - partners stop flying, customs rules change, costs move. The lane stops; the numbering system does not. Numbers issued just before a pause stay in state 1 permanently.
On one lane I looked at recently, more than half of the numbers had never produced a single movement scan, nearly all of them resting on a status that means announced but not booked in. That is not a tracking failure. That is state 1, rendered honestly.
What to change
Distinguish "never scanned" from "no recent scan". They need different copy and different escalation.
if (events.length === 0 && !everHadEvents) return 'Not booked in yet' // seller's problem
if (events.length > 0 && isStale(lastEvent)) return 'No recent scan' // transit problem
Do not retry state 1 on a tight loop. Nothing changes until goods are physically handed over. Back off hard on numbers that have never scanned; carriers rate-limit, and you are spending your budget on the population least likely to answer.
Do not match the carrier by name. The short code on an invoice frequently is not the prefix inside the number - one operator I checked is billed under four letters while every one of its numbers opens with three different ones and closes with two more. Resolve by the number's shape, not by a name string from a dropdown, or you will route valid numbers to the wrong carrier.
Store which party produced the latest scan. After the handover, the consolidator cannot answer a doorstep question - a different company is holding the parcel. If your UI does not surface that, your agents will chase the wrong one.
The honest answer to show a customer
Your number is valid. No carrier has scanned it yet, which usually means the parcel has not been handed over. Your seller can confirm that faster than any tracking page.
That is a better support reply than a spinner, and it is true far more often than "not found" is.
Written with AI assistance. I work on 24hTrack (https://www.24htrack.com), a free package tracker for 3,200+ carriers - paste any tracking number, the carrier is detected automatically, no sign-up. There is a REST API and an MCP server at https://www.24htrack.com/api if you want this programmatically.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.