Locate a shipment and explain its tracking timeline

The job is to answer one question for one package: where is it right now, how did it get there, and what should the customer be told? This is a single-package lookup. Do not turn it into a portfolio review of exceptions or expired shipments; that is a different job. Your output should let a support agent reply to the customer without opening the admin.

1. Pin down the identifier and its type

Ask what the user has, then use exactly one locator. Each one behaves differently:

• Tracking number: the most precise. Use the tracking_numbers filter with list_shipments. Strip spaces and prefixes the user pasted in; a carrier number is usually one unbroken string.
• Order number: use the order_number filter. One order can hold several shipments (split fulfilment), so expect more than one candidate.
• Customer email: use customer_emails. This is the broadest and most likely to match several shipments across time. Narrow it with a date range before reading details.

No date range is needed for the first three locators. Add one only when the result set is large.

2. Resolve to exactly one shipment

list_shipments returns candidates; get_shipment returns the detail for one. Never guess the internal shipment id.

• One match: proceed with it, and state which tracking number and order you resolved to.
• Several matches: list the candidates (tracking number, order, status, created date, carrier) and ask the user which one they mean. Do not pick the newest by default; a split order may need all of them explained.
• No match: try the next locator the user can supply (order number, then email, or the tracking number with and without spacing). If nothing matches after two attempts, say so and ask for a different identifier. Do not infer a shipment from a similar number.

Once resolved, call get_shipment for the full record: current status and sub-status, latest carrier events and the complete checkpoint timeline.

3. Read the timeline in the right order

• Start from the latest checkpoint and the current status, then work backwards. The answer to "where is it" is at the top; the history explains how it got there.
• Distinguish status from sub-status. A status such as in transit or delivered is coarse. The sub-status says why it is there: out for delivery, delayed at customs, awaiting pickup. Quote the sub-status when it is more specific.
• Check the timestamps, not just the sequence. A checkpoint gap of several days in an otherwise active route is a stall. A long wait at one location is more informative than the event that ended it.
• Note the carrier and the country or hub changes. Cross-border handoffs are where most delays happen. Say so when the delay sits at a customs or transfer step.
• Compare the expected delivery window with today. If the package is past its window, say by how many days, and say that it is past the carrier's estimate, not that it is lost.

4. Translate into what the customer needs

Give the support agent a plain-language statement they can relay, separate from the raw log:

• Where the package is, in one sentence.
• Whether it is moving normally, stalled, or past its estimate.
• What the next expected event is, if the timeline supports one.
• What the agent can and cannot promise. You may not guess an arrival date beyond what the carrier data shows.

Common patterns and traps

• Delivered but customer says not received. The checkpoint says delivered. Report the delivery checkpoint with its time and location, and do not contradict the customer. Next step is a delivery investigation, not a re-track.
• Status looks stuck, checkpoints look fine. Old checkpoints can be sparse for some carriers. A long gap alone is not proof of loss; say the data is thin rather than that the package is missing.
• Two shipments, one order. Split fulfilment is common. Always show every shipment for the order, or the customer will think the other part was never sent.
• Email matches the wrong person. A shared or reused email can return another customer's shipments. Confirm with an order number or tracking number before reporting details.
• Tracking number pasted with spaces or hyphens. Normalise it and retry before concluding that it does not exist.
• Expired or exception status. These are findings, not dead ends. Report what the timeline shows about the cause, but do not run a bulk triage here.
• Stale cache impression. Say when the last checkpoint occurred so the support agent knows how fresh the picture is.

Output

Shipment: <tracking number> · order <order number> · carrier <carrier>
Resolved by: <tracking number | order number | email>, <n> candidate(s) considered
Current: <status> / <sub-status>, last update <date, location>
Expected: <delivery window, or "no estimate given">  Position: <on track | past estimate by N days | no estimate>
Timeline (newest first):
  <date time> · <location> · <event>
  ...
Stalls or gaps: <gap and location, or "none">
For the customer: <one plain sentence the agent can relay>
Not established: <what the carrier data does not show>

Rules

• Do not change the shipment while looking it up. Any write tool, such as update_shipment, retrack_shipment or mark_shipment_status, needs the user's explicit yes before you call it, and you should not call one unless the user has asked for a change.
• Do not mark a shipment as lost, delivered or returned to sender from a timeline reading alone. Recommend it if warranted, then wait for the user's explicit yes.
• Never invent a delivery date, carrier event or checkpoint. Quote only what get_shipment returned.
• Never report a refund, exchange or compensation as arranged. This job does not decide those.
• Do not treat a customer email as proof of identity; confirm with an order or tracking number before showing detailed records.
• Do not pick one shipment from several silently. Ask.

Done when

• One shipment is resolved and named by tracking number and order, or the user has been asked to choose between explicit candidates.
• The current status, sub-status and most recent checkpoint are stated with their times and locations.
• Any stall or delay is located on the timeline, and any "past estimate" claim is quantified in days.
• A plain-language line for the customer is given.
• The "Not established" line says what the carrier data does not show, and whether the timeline is thin or complete.