Stale shipment tracking data: cache freshness and outage fallback

Understand the four useful response situations

A live result comes from a successful acquisition. A normal cached response uses the verified snapshot within the 30-minute cache window. data_freshness describes the state and age; last_checked_at is the verification time, not necessarily the carrier’s latest scan time.

A stale fallback is available only when allow_stale: true was requested, the ordinary cache is expired, the live source attempt fails and an eligible previously verified snapshot is younger than 24 hours. If no eligible snapshot exists, the lookup remains unavailable. The fallback does not claim new source evidence.

Opt in from the backend, not by relabelling an error

Keep the API key server-side and choose the fallback policy deliberately. The example below waits for the documented lookup path, checks the HTTP response and records the returned freshness state. It does not convert a failed request into a fake pending response.

Set TRACKING_NUMBER to a real authorized parcel number. Successful direct, cached and stale responses use monthly lookup quota. Failed lookups release their reserved monthly slot, but you should still bound retries and respect admission limits.

const number = process.env.TRACKING_NUMBER;
if (!number) throw new Error('Set TRACKING_NUMBER');
const response = await fetch('https://api.traceapi.dev/v1/track', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.TRACE_API_KEY}`,
    'Content-Type': 'application/json' },
  body: JSON.stringify({ tracking_number: number, allow_stale: true }),
  signal: AbortSignal.timeout(95000)
});
const body = await response.json();
if (!response.ok) {
  console.warn('Tracking update unavailable', body.error?.code,
    response.headers.get('Retry-After'));
} else {
  const olderSnapshot = body.stale === true || body.data_freshness?.state === 'stale';
  console.log(olderSnapshot ? 'Older verified snapshot' : 'Verified timeline',
    body.last_checked_at, body.data_freshness?.age_seconds);
}

Write customer messages that describe the actual evidence

Use copy such as ‘In transit — last verified yesterday; a new update is temporarily unavailable’ for a stale snapshot. Keep the last check time visible and distinguish it from the scan’s own time. Do not update a ‘last refreshed’ label to now simply because your backend received an older cached object.

For a completely unavailable result, say that tracking could not currently be retrieved. Do not convert it to ‘Label created,’ ‘No movement’ or ‘Delivered’ without supporting scans. Your order’s payment and fulfillment states should remain unchanged by a tracking-source failure.

For example, a WooCommerce customer can still see the previous in-transit scan during an outage, while support sees the original verification age. A marketplace should apply that label to the affected parcel rather than claiming every parcel in the order is up to date.

Keep stale snapshots out of new-event actions

Trace does not generate shipment notifications or watch changes from stale fallback data. Your application should apply the same principle to downstream actions: reading an older delivered snapshot must not resend a delivery email or trigger another refund workflow.

Use durable event identities for webhook-driven business actions. If your local projection was lost, reconcile from the owned shipment record and known event history rather than treating every successful GET or lookup as a new event. Arrival of an HTTP response is not a new carrier scan.

Measure source freshness independently from service health

The API’s readiness check tests required service dependencies, not every carrier page. A healthy API can still return tracking_sources_unavailable for a particular parcel or source. Measure verified-result success, observation age, fallback frequency and carrier/destination behavior separately from infrastructure readiness.

A high stale-fallback rate is a signal to investigate acquisition or source qualification, not a reason to extend a freshness label indefinitely. Keep an error path after the 24-hour fallback eligibility window and retain a support route for disputed or important delivery evidence.

• Test live, cached, eligible stale and no-eligible-snapshot states in your application fixtures.
• Confirm that last_checked_at stays tied to the prior verification in stale responses.
• Respect Retry-After where supplied and use bounded retries rather than tight polling.
• Do not compute a no-scan alert from a failed or stale lookup.
• Track cached and stale successes in the same account lookup budget as live successes.

Common questions

References & next steps

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

• Trace direct lookup and allow_stale behavior
• Trace freshness response fields
• Trace service-health scope