Shipment Statuses
Every shipment has a status field that reflects the latest known state from the carrier. This page documents every possible status value, whether it triggers customer notifications, and how carrier-reported statuses map to notification events.
Active / Trackable Statuses
These statuses represent shipments that are in progress or have reached a terminal delivery state.
| Status | Label | Description | Triggers Notification? |
|---|---|---|---|
pending | Waiting | Shipment registered, waiting for first carrier scan | No |
pre_transit | Label Created | Label created, not yet picked up by carrier | Email (in_transit trigger) |
in_transit | In Transit | Carrier has picked up and is transporting the package | Email + SMS (if enabled) |
available_for_pickup | Ready for Pickup | Package at facility, ready for customer pickup | Email (in_transit trigger) |
out_for_delivery | Out Today | Package is on the delivery vehicle today | Email + SMS (if enabled) |
delivered | Delivered | Successfully delivered to recipient | Email + SMS (if enabled) |
exception | Issue | Delivery problem: failed attempt, wrong address, etc. | Email + SMS (if enabled) |
on_hold | On Hold | Package paused at a carrier facility | Email (if enabled) |
failure | Failed | Delivery failed, return initiated | Email (if enabled) |
return_to_sender | Returning | Package is being returned to the sender | Email (if enabled) |
Terminal / System Statuses
These statuses indicate a non-trackable or error state. They do not trigger customer notifications.
| Status | Label | Description |
|---|---|---|
unknown | Unknown | Carrier returned an unknown or unrecognized status |
label_cancelled | Label Canceled | Shipping label was voided before pickup |
deleted | Deleted | Shipment has been removed from the system |
expired | Expired | Tracking number expired with no movement |
invalid_tracking | Invalid Number | Tracking number not recognized by the carrier |
invalid_carrier | Invalid Carrier | Carrier slug is not supported |
carrier_unsupported | Unsupported | Carrier is not available in the tracking engine |
cancelled | Canceled | Shipment was cancelled |
Notification Triggers
The Notification Service maps carrier-reported statuses to trigger events. Multiple raw statuses can map to the same notification trigger — for example, pre_transit, in_transit, and available_for_pickup all map to the shipment.in_transit trigger. The same notification is only sent once per trigger per shipment.
| Statuses | Notification Trigger |
|---|---|
pre_transit, in_transit, available_for_pickup | shipment.in_transit |
out_for_delivery | shipment.out_for_delivery |
delivered | shipment.delivered |
exception, failure, on_hold | shipment.exception |
return_to_sender | shipment.returned |
Email Template Mapping
Email templates are grouped by status category. Configure templates in Dashboard → Stores → Email.
| Statuses | Email Template Key |
|---|---|
pre_transit, in_transit | in_transit |
available_for_pickup | available_for_pickup |
out_for_delivery | out_for_delivery |
delivered | delivered |
exception | exception |
failure | failure |
return_to_sender | return_to_sender |
on_hold | on_hold |