Spot delivery problems and email customers before they ask

I want to know about delivery problems before the customer emails us. Run this workflow on a webhook from Shippo subscribed to the track_updated event. Shippo posts the full Tracking object every time a shipment changes status, so the incoming body carries the carrier, the tracking number, a tracking_status object with status, substatus and status_details, and a free form metadata field.

Decide first whether this update is a real delivery problem, and stop immediately if it is not. Most updates are routine and must be ignored: do not email anyone, do not open a ticket, and do not record anything for a package that is simply moving normally. Treat PRE_TRANSIT and ordinary TRANSIT scans and any DELIVERED update as routine and exit. Treat the update as a problem when the status is FAILURE or RETURNED, and also when the status is still TRANSIT but the substatus signals an exception rather than normal movement. That second case matters, because carriers usually report bad addresses, missed attempts, holds and delays while the shipment is still technically in transit, so filtering on the top level status alone would miss most real problems. Substatus codes that count as exceptions include address_issue, delivery_attempted, package_damaged, delayed and any held or customs related code, and the substatus also carries an action_required flag which should be treated as a problem whenever it is true.

Once an update qualifies, gather the full picture. Call Get Tracking Status in Shippo with the carrier and tracking number from the webhook to pull the complete tracking history, the latest scan location, and the current and original estimated delivery dates, so you can see how long the package has been stuck and whether the delivery estimate has already slipped.

Then find the order. The Shippo metadata field on the shipment is where the order reference is stored when the label is bought, usually in a form like Order 000123. Read the order id or order number out of metadata and call Get Order in Shopify to get the customer name, the customer email address, the line items, and the order value. If metadata has no usable order reference, or the lookup does not find a matching order, then skip the customer email entirely, because the customer name and email address only exist on the order and you must never guess a recipient. In that case still open the support ticket below and state clearly at the top of it that the shipment could not be matched to an order, so a human can match it manually.

Judge the severity yourself from the carrier substatus and status details rather than treating every exception the same. A package damaged in transit or a shipment being returned to sender is severe and usually needs a replacement or refund conversation. A bad or incomplete address and a failed delivery attempt are urgent but fixable, and normally need something from the customer such as a corrected address or a redelivery choice. A customs hold or a weather delay is usually outside anyone's control and mainly needs an honest explanation and a realistic timeline. Weigh the order value too, since a high value order deserves a more careful response.

Write the customer a short plain English email and send it with Send a Message in Gmail to the email address on the order. Keep it to a few sentences. Say what happened to their package in ordinary language, never in carrier jargon or raw status codes, say what you are doing about it, and tell them the one thing you need from them if you need anything at all, such as confirming their address. Give a realistic next step or timeline instead of a vague apology, reference what they actually ordered so it reads like a real person looked at it, and include the tracking number for their reference. Do not promise a refund or a replacement unless the situation is clearly severe, such as a damaged or returned package.

At the same time open a ticket with Create Ticket in Zendesk so support owns the follow up. Put the tracking number in the subject line and keep the subject format identical every time, for example a delivery exception label, then the tracking number, then a short description of the problem, so that repeat updates about the same troubled shipment are easy to spot together instead of looking like unrelated tickets. In the ticket body include the carrier and the carrier substatus with its status details, the latest scan location and time, the current and original estimated delivery dates, the order number, the order value and the line items, the customer name and email address, your severity judgement with a one line reason, and whether the customer has already been emailed. Both the email and the ticket should happen for every qualifying update.