--- name: aftership-post-purchase-locate-shipment-and-tracking-timeline description: Resolve one customer's or order's shipment from a tracking number, order number or customer email, then explain its current state, latest carrier events and full checkpoint history, so support can answer "where is my package" accurately. Use when the user gives a tracking number, order number or customer email and asks where a package is, what happened to it, or why it has not arrived. --- # 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: · order · carrier Resolved by: , candidate(s) considered Current: / , last update Expected: Position: Timeline (newest first): · · ... Stalls or gaps: For the customer: Not established: ``` ## 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.