Developer guides

Shipment not updating: design evidence-based no-scan alerts

For support teams investigating parcels that appear to have stopped updating.

By Trace · Reviewed

“The parcel has not moved” and “we could not retrieve an update” are different claims. A source outage gives you no new evidence about movement. A no-scan alert should depend on a successfully verified history, not simply the age of the last request.

Trace distinguishes carrier-fact exceptions from its inferred no-recent-scan rule. Keep that attribution visible to operators so an inference does not become a supposed carrier announcement.

Require evidence before starting the clock

Trace’s no-scan inference requires a successful verified observation and UTC instants for every scan. The threshold stalled_after_hours defaults to 72 hours and can range from 24 to 720. Unknown local times, failed lookups and stale fallback results do not establish a stall.

This protects against comparing guessed timezones or treating an unavailable carrier page as proof of a stalled parcel. If the evidence is ineligible, show the reason and investigate acquisition separately.

Separate the operator’s next action by evidence

Read the latest scan, last verification time and monitoring diagnostics together. A successful check with an old eligible scan warrants a different investigation from a quota-postponed refresh.

Observed conditionInterpretationNext action
Verified old UTC scansEligible no-scan inference may apply.Review threshold and carrier context.
Unknown scan timezoneElapsed time cannot be established safely.Preserve local text; avoid a precise age claim.
503 lookup failureNew movement could not be checked.Investigate source availability.
Quota postponementThe refresh was not completed.Inspect quota and next refresh state.
Carrier exceptionThe source reported a specific condition.Review the exception evidence and suggested action.

Keep acknowledgement separate from clearance

Acknowledging an alert records that an operator saw it. Assigning an owner label records responsibility. Resolving an investigation records a human outcome, but does not change the underlying carrier evidence or make a parcel move.

A subsequent verified observation can clear the rule condition. A new recurrence after verified clearance can reopen the workflow. Keep notes and timestamps so the next operator can distinguish an old investigation from a new episode.

Use careful customer wording

Prefer “We have not seen a newer carrier scan since…” when the scan time is known. For retrieval failures, say “We could not refresh the tracking information” and retain the last verification time. Avoid automatically calling a parcel lost or promising a new delivery date.

Test with a verified old timeline, an unknown-timezone timeline, an acquisition failure and a resumed scan. The alert should appear only for the eligible case and should not persist as a current condition after verified clearance.

Common questions

Does a no-scan alert prove a parcel is lost?

No. It is an investigation aid based on observed history and a configured threshold. A carrier or merchant investigation is needed to establish the actual outcome.

References & next steps

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