How can I detect shipments that haven't updated for several days?

Why Inactive Shipments Are Hard to Catch Early

Standard carrier tracking APIs do not send webhooks when a parcel stops moving. A package sitting forgotten in a corner of a regional transshipment center still carries the exact same tracking status as a package traveling on an express flight. The carrier's public tracking portal continues to report “In Transit” without raising any flags.

Without automated inactivity detection, e-commerce operations teams only learn about stranded consignments when the customer contacts support to ask where their order is. By that point, the package may have been sitting without movement for several days without anyone noticing.

Detecting inactive shipments requires continuous timestamp comparison across every open parcel. Each carrier uses distinct date formats, differing time zone representations, and non-standard checkpoint descriptions. A reliable detection system must filter out terminal states, parse checkpoint timestamps into UTC, and evaluate elapsed hours against operational thresholds.

What rule determines when a shipment is marked as stuck?

In ClearTrack AI, an active consignment is classified as stuck when the elapsed time since its latest verified carrier checkpoint exceeds 72 hours. When this threshold is crossed, the API automatically marks insights.is_stuck as true, sets insights.requires_attention to true, and designates the trigger reason as attention_reason: "stuck".

The 72-hour inactivity rule applies strictly to active transit stages. Shipments in terminal states — specifically delivered, rto_delivered, and cancelled — are entirely excluded from stuck evaluations. Once a parcel is physically delivered to the recipient or safely returned to the origin warehouse, its delivery lifecycle is complete. In these terminal states, hours_since_last_scan evaluates to null and is_stuck evaluates to false.

Active tracking responses are cached for up to 30 minutes to reduce upstream load on carrier networks while ensuring freshness. Terminal states are cached permanently. If an upstream carrier tracking portal experiences temporary downtime, ClearTrack AI returns the last known checkpoint scans with a stale: true indicator rather than dropping the shipment data.

What causes false positives and how do you handle them?

Not every multi-day gap in tracking scans indicates a lost parcel. Indian logistics networks operate under distinct regional conditions that can temporarily pause scan events without risking shipment failure:

• Sunday Hub Pauses: Many delivery branch offices and commercial logistics stations pause delivery operations on Sundays. A package arriving at a destination delivery hub on Saturday night may not receive an “Out for Delivery” scan until Monday morning.
• National and Regional Holidays: Extended holidays such as Diwali, Eid, or regional state elections frequently halt line-haul movement and local delivery shifts.
• Long-Distance Surface Corridors: Shipments moving by road to remote destinations like the North Eastern states, Jammu & Kashmir, or island territories travel on long multi-day line-haul trucks without intermediate sorting scans.
• Batch-Update Carrier Systems: Some regional carriers load line-haul containers without intermediate scans, recording checkpoints only upon arrival at the destination hub.

Setting the inactivity threshold to 72 hours prevents normal weekend gaps from firing false alerts. Late deliveries aren't rare: in our dataset of 9,155 shipments from 3 D2C brands (May 2025–June 2026), 20.8% arrived after the courier's own estimated date.

How can I build DIY stuck detection with my own database?

If you choose to build stuck detection inside your own infrastructure, you must store the latest event timestamp for each open order and evaluate elapsed time using a scheduled cron worker.

Here is a sample SQL query in PostgreSQL to identify shipments where the latest scan is older than 72 hours:

SELECT 
  tracking_number, 
  carrier, 
  status, 
  last_scan_at,
  ROUND(EXTRACT(EPOCH FROM (NOW() - last_scan_at)) / 3600) AS hours_since_last_scan
FROM shipments
WHERE status NOT IN ('delivered', 'rto_delivered', 'cancelled')
  AND last_scan_at < NOW() - INTERVAL '72 hours';

If you build this custom normalizer yourself, you may want to configure per-carrier thresholds as an implementation detail. For example, you might choose a shorter window like 48 hours for express air shipments on metro routes, and a longer window like 96 hours for rural postal deliveries.

ClearTrack AI eliminates this database parsing and cron overhead by computing insights.is_stuck, insights.hours_since_last_scan, and insights.transit_days_elapsed automatically on every tracking lookup.

What should you do when a shipment is flagged as stuck?

When your polling worker flags a shipment with insights.is_stuck === true, execute a structured three-step response workflow:

1. Send a Proactive Customer Notice: Notify the buyer by SMS or WhatsApp that their order is in transit and experiencing a temporary hub routing delay. Keeping the buyer informed before they ask eliminates anxiety and prevents inbound WISMO tickets.
2. Escalate to the Courier: Send your account manager the tracking number, last recorded hub, and hours since the last scan so the operations desk can trace the parcel.
3. Trigger Replacement for Priority Orders: For high-value orders or expedited deliveries where inactivity reaches five to seven days, initiate a replacement order from your warehouse to protect the customer relationship.

How do I query stuck shipment insights from the ClearTrack AI API?

You can query tracking information for any supported courier using a single HTTP GET request:

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.cleartrackpromise.in/v1/track/indiapost/CP100000004IN"

Trimmed API Response Payload

The response includes unified status details alongside the structured insights object:

{
  "tracking_number": "CP100000004IN",
  "carrier": "indiapost",
  "status": "in_transit",
  "status_text": "Item Dispatched to Hub",
  "is_delivered": false,
  "is_rto": false,
  "last_known_location": "New Delhi NSH",
  "cached": true,
  "stale": false,
  "delivery_attempts": {
    "count": 0,
    "attempts": []
  },
  "insights": {
    "current_stage": "in_transit",
    "is_stuck": true,
    "hours_since_last_scan": 101.5,
    "transit_days_elapsed": 4.2,
    "requires_attention": true,
    "attention_reason": "stuck"
  }
}

Automated Audit Worker in Node.js / TypeScript

The script below demonstrates how to query open orders and trigger escalations when a shipment is flagged as stuck:

interface TrackingInsightResponse {
  tracking_number: string;
  carrier: string;
  status: string;
  insights: {
    current_stage: string;
    is_stuck: boolean;
    hours_since_last_scan: number | null;
    transit_days_elapsed: number | null;
    requires_attention: boolean;
    attention_reason: string | null;
  };
}

async function auditOpenShipment(carrier: string, awb: string): Promise<void> {
  const response = await fetch(
    `https://api.cleartrackpromise.in/v1/track/${carrier}/${awb}`,
    {
      headers: {
        "X-API-Key": process.env.CLEARTRACK_API_KEY || "YOUR_API_KEY",
        "Accept": "application/json",
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to fetch tracking: ${response.status}`);
  }

  const data = (await response.json()) as TrackingInsightResponse;
  const { insights } = data;

  if (insights.is_stuck) {
    console.warn(
      `Shipment ${awb} is stuck in stage "${insights.current_stage}" ` +
      `with no scan for ${insights.hours_since_last_scan} hours.`
    );
    // 1. Notify customer via WhatsApp/SMS
    // 2. Open carrier tracer ticket
  }
}

You can test this in your development environment by signing up to start a free trial or inspecting our prepaid lookup plans. For more tracking tutorials, see our developer guides.

Frequently Asked Questions