Why "Delivered" Can Appear Mid-Journey: Parsing Multi-Leg Tracking Histories
If you build anything that consumes carrier tracking data — an order dashboard, a WISMO bot, a support macro, a "where is my order" email — there is one parsing assumption that will bite you eventually: description CON
If you build anything that consumes carrier tracking data — an order dashboard, a WISMO bot, a support macro, a "where is my order" email — there is one parsing assumption that will bite you eventually:
description CONTAINS "delivered"does not mean the parcel reached the customer.
I work on 24hTrack, a free package tracker that normalises scans across 3,200+ carriers, and this is the single most common cause of a wrong status reaching an end user. Here is the shape of the problem and how to handle it.
The multi-leg history
Plenty of cross-border services are not end-to-end carriers. One company collects the parcel, flies it, clears customs — then hands it to a delivery company in the destination country for the last leg.
That handover gets written into the history as its own scan. A real example of the sequence (wording simplified, one service, origin to a US address):
Shipment information received
Arrived at origin facility
Departed from sort facility
Arrived at the origin international airport
Clearance processing completed - Export
Departed from airport
International flight has arrived
Start customs clearance
Collected at cargo terminal
Clearance processing completed - Import
Delivered to local carrier <-- handover, NOT your delivery
Accepted at USPS facility
Arrived at USPS facility
Departed USPS facility
Arrived at post office
Out for delivery
Delivered, Front Door/Porch <-- actual delivery
Note line 11 and line 17. Both contain the token delivered. Only one of them means the customer has the box. On the histories I looked at for this service, the real delivery landed several days after the handover line.
The same thing happens on European lanes, where the handover is followed by a local courier's own depot scans and then its own delivery wording.
Why naive matching fails
Three patterns that look reasonable and are not:
# 1. substring — matches the handover line
if "delivered" in desc.lower(): ...
# 2. word boundary — same problem, the handover line
# literally contains the word
if re.search(r"\bdelivered\b", desc, re.I): ...
# 3. "last event wins" — correct only if you are certain
# the history is complete and ordered
status = events[-1]
Pattern 3 deserves its own warning. Not every source returns events newest-first, and not every source returns a complete history. If you take events[0] from a source that returns oldest-first, you will report "shipment information received" on a parcel that was delivered last week.
What actually works
Check the object, not just the verb. The useful signal is who took possession. A scan reading delivered to local carrier, delivered to agent, handed over to <company>, transferred to partner is a transfer of custody between companies. A scan naming a place at the destination — a door, a porch, a mailbox, a parcel locker, a reception desk, a named individual — is the delivery.
HANDOVER = re.compile(
r"\b(deliver(?:ed|y)\s+to\s+(?:local\s+carrier|agent|partner)"
r"|handed?\s+over\s+to"
r"|transferred\s+to\s+(?:partner|local))\b", re.I)
def is_final_delivery(desc: str) -> bool:
if HANDOVER.search(desc):
return False # custody moved, journey continues
return bool(re.search(r"\bdeliver(?:ed|y\s+complete)\b", desc, re.I))
Two things that matter more than the regex itself:
- Order the exclusion before the inclusion. If you test for "delivered" first and try to subtract handovers afterwards, any rule you add later lands on the wrong side of the branch.
-
Negations are a separate class.
could not be delivered,delivery attempt failed,delivery to parcelshop failedall contain the verb and all mean the opposite. These are alerts, not deliveries, and getting them wrong hides a failed attempt from the customer.
Why it matters beyond correctness
A wrong "delivered" is expensive in a specific way: it freezes the record. If your system stamps a delivered_at on the handover line and then treats the shipment as terminal, you stop polling and the real delivery scan never lands. The customer is looking at a status that cannot self-correct, and your support queue absorbs the difference.
It also sends people to the wrong company. The firm whose name is on the tracking number is frequently not the firm that knocked on the door, which means it holds no delivery photo, no signature and no address. On most routes the retailer is the carrier's customer, so the retailer is the party who can request proof of delivery — and that is the right thing to tell a user who says the parcel never arrived.
Short version
-
"delivered" in descis not a delivery check. - Exclude custody transfers before matching the verb, and treat negations as their own class.
- Do not mark a shipment terminal on a handover line, or it can never correct itself.
- If a user wants delivery proof, point them at the final-mile carrier via the retailer, not at whoever issued the original number.
If you want to see a normalised multi-leg history without wiring up an integration first, you can paste any number into 24hTrack — carrier detection is automatic and there is no sign-up. Carrier-specific notes live under 24htrack.com/carriers.
Disclosure: I work on 24hTrack. Written with AI assistance; the scan sequences and the behaviour described were checked against real tracking histories before publishing.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.