WISMO AI agents & synchronous tracking

Customer support workflows—especially "Where Is My Order?" (WISMO) AI agents, helpdesk bots, and order-status pages—are triggered when a shopper asks about a package right now.

lastscanned is designed for synchronous, single-request tracking: pass a tracking number to GET /v1/track/{trackingNumber} (or call the track_package MCP tool) and get the normalized status, estimated delivery, cross-border handoff number, and full scan history in one response across all 31 supported carriers.

1. Synchronous GET vs. webhook pre-registrationCopy Anchor Link

Most legacy tracking aggregators are built around asynchronous webhook pipelines:

1. You POST a tracking number to register a tracker on their platform.
2. Their queue schedules an asynchronous background job.
3. You wait seconds or minutes for an inbound webhook before your app has any scan events to show the customer.

That model breaks down in interactive AI agents, customer support chat, and on-demand order lookup routes where a customer pastes a tracking number or asks "Where is my order #10492?" and expects an immediate answer.

2. Normalized status lifecycle (status enum)Copy Anchor Link

Every carrier uses different internal event codes and phrasing. lastscanned normalizes both the top-level parcel state (status) and each individual scan event (events[].status) into a deterministic 7-value enum so your WISMO agent or support router can branch cleanly:

What if a brand-new label isn't in the carrier's system yet? When a merchant prints a label that the carrier has not indexed yet, the API returns HTTP 404 with error.code: "not_found". In a WISMO bot, treat not_found on orders created within the last 24–48 hours as pre-transit ("Your shipping label was just created and is waiting for the carrier's first scan").

3. Resolving cross-border handoffs & the "USPS Currently Awaiting Package" consolidator black holeCopy Anchor Link

A. Cross-border last-mile handoffs (message)Copy Anchor Link

One of the most common WISMO failure modes happens on cross-border e-commerce shipments (yanwen, cainiao, yunexpress, 4px, cne, sunyou, ubi, asendia). A shopper receives a tracking number like YT2412345678901234, 3A5V700123456, or AHOY7K2M9Q4T, sees "Arrived at destination airport" or "Handed over to local courier," and asks support which company is actually delivering to their door.

When a cross-border carrier hands a parcel to a domestic last-mile carrier (such as USPS, UniUni, GOFO, SpeedX, OnTrac, Cirro, Canada Post, Intelcom / Dragonfly, Australia Post, or Royal Mail), lastscanned automatically extracts the handoff information and populates the top-level message field:

{
  "carrier": "yunexpress",
  "trackingNumber": "YT2412345678901234",
  "status": "in_transit",
  "statusDescription": "In transit",
  "service": "YunExpress Standard",
  "deliveredAt": null,
  "deliveredAtLocal": null,
  "signedBy": null,
  "destination": { "city": null, "state": null, "country": "US" },
  "estimatedDelivery": null,
  "estimatedDeliveryAt": null,
  "message": "Handed to UniUni as UUSC000019638703",
  "events": [
    {
      "timestamp": "2026-10-25T18:40:00Z",
      "localTime": "2026-10-25T14:40:00",
      "status": "in_transit",
      "description": "Arrived at local facility",
      "location": "LOS ANGELES, CA, US",
      "code": null
    }
  ]
}

1. Always inspect message on yanwen, 4px, cainiao, yunexpress, cne, sunyou, ubi, and asendia responses.
2. Surface the doorstep carrier and secondary tracking number directly to the customer (for example, "Your package cleared customs via YunExpress and was handed to UniUni for local delivery under tracking number UUSC000019638703").
3. Optionally chain a second lookup: if the customer wants the granular local doorstep scans, call GET /v1/track/UUSC000019638703 (or track_package) with the secondary tracking number extracted from message.

B. Solving "USPS Currently Awaiting Package" on 92… consolidator labels (?carrier=osm / ?carrier=pitneybowes)Copy Anchor Link

The second major WISMO spike comes from domestic parcels shipped through postal consolidators like OSM Worldwide and Pitney Bowes. These parcels carry a standard 22-digit 92… USPS IMpb barcode (or 30-digit 420 + ZIP + 92…), so querying USPS directly returns status: "label_created" with "Picked Up by Shipping Partner, USPS Awaiting Item" ("USPS Currently Awaiting Package") for 3–7 days while the consolidator trucks the parcel across the country.

In your WISMO agent:

• If a 92… USPS lookup returns status: "label_created" and the scan text mentions "OSM WORLDWIDE", "PITNEY BOWES", or "Shipping Partner", immediately query the exact same 92… number with ?carrier=osm or ?carrier=pitneybowes (or pass carrier: "osm" / "pitneybowes" in MCP).
• You will get back the live middle-mile sort center arrivals/departures (e.g. Glendale Heights, IL, Atlanta, GA, Monroe Twp, NJ) and the consolidator's estimatedDelivery date so your AI agent can give the shopper a real transit update instead of repeating "USPS is still waiting for your package."

4. Copy-paste integration patternsCopy Anchor Link

Option A: Remote MCP server (zero code)Copy Anchor Link

If your AI agent or support platform supports the Model Context Protocol (Streamable HTTP), point it directly at https://mcp.lastscanned.com. Your agent immediately gains track_package, track_packages (up to 100 numbers per call), and list_carriers.

{
  "mcpServers": {
    "lastscanned": {
      "url": "https://mcp.lastscanned.com",
      "headers": {
        "Authorization": "Bearer lsk_live_YOUR_API_KEY"
      }
    }
  }
}

Option B: TypeScript / Next.js Route Handler & AI SDK toolCopy Anchor Link

For custom support bots, Shopify/order portals, or serverless API routes, call GET https://api.lastscanned.com/v1/track/{trackingNumber} directly from your server:

export interface TrackingEvent {
  timestamp: string | null;
  localTime: string | null;
  status:
    | "label_created"
    | "in_transit"
    | "out_for_delivery"
    | "delivered"
    | "exception"
    | "returned"
    | "unknown";
  description: string;
  location: string | null;
  code: string | null;
}

export interface TrackingResponse {
  carrier: string;
  trackingNumber: string;
  status: TrackingEvent["status"];
  statusDescription: string;
  service: string | null;
  deliveredAt: string | null;
  deliveredAtLocal: string | null;
  signedBy: string | null;
  destination: {
    city: string | null;
    state: string | null;
    country: string | null;
  } | null;
  estimatedDelivery: string | null;
  estimatedDeliveryAt: string | null;
  message?: string;
  events: TrackingEvent[];
}

export async function getOrderTracking(
  trackingNumber: string,
  carrier?: string,
): Promise<TrackingResponse> {
  const url = new URL(
    `https://api.lastscanned.com/v1/track/${encodeURIComponent(trackingNumber.trim())}`,
  );
  if (carrier) url.searchParams.set("carrier", carrier);

  const res = await fetch(url, {
    headers: {
      Authorization: `Bearer ${process.env.LASTSCANNED_API_KEY}`,
    },
    // Fresh status on customer inquiry
    cache: "no-store",
  });

  if (!res.ok) {
    const err = await res.json().catch(() => null);
    throw new Error(err?.error?.message ?? `Tracking lookup failed (${res.status})`);
  }

  return res.json() as Promise<TrackingResponse>;
}

Because the Pro plan ($4.99/month) bills per unique tracking number per billing period (with 1,000 unique numbers included and $0.015 per extra unique number), your WISMO bot can call getOrderTracking() every time a customer refreshes their order page or asks for an update without paying per poll.