Status vocabulary
Every shipment carries one status from a fixed list. Audience: store admins + CS leads running day-to-day fulfillment.
Admins do not add their own codes. Integration-specific codes map into this list via status mappings.
The statuses#
Enum: fostercommerce\shipments\enums\Status. Who sets it: you (or your 3PL, reporting through an integration), from the shipment edit page, the REST API, or an inbound webhook.
| Value | Label | Typical use |
|---|---|---|
new |
New | Default state. Created, not yet worked. |
in_progress |
In progress | Being prepared (picking, packing, labeling). |
on_hold |
On hold | Paused (stock issue, fraud review, address verification). |
fulfilled |
Fulfilled | Warehouse work is done. |
shipped |
Shipped | In the carrier’s hands. See the behavior below. |
cancelled |
Cancelled | Won’t ship. |
A status is a label. The plugin does not attach hidden behavior to most of these values: what a status triggers (an email, a push to an integration) is something you configure, not something baked into the code.
You decide what each status means#
The “typical use” column is a suggestion, not a rule. Your store chooses how to use the available statuses to fit your workflow. One store treats fulfilled as “packed and ready, not yet shipped”; another treats it as the moment the order is effectively done. Both are correct.
The plugin does not track detailed carrier events (there is no delivered, in_transit, out_for_delivery, and so on). It models the merchant’s side of fulfillment, so the last status you set is often the final word on a shipment. If you need carrier-level tracking detail, that is the job of the carrier’s own tracking page, not this plugin.
Two statuses carry behavior of their own, described next: shipped advances the order, and cancelled is written for you when an order enters a status that cancels its shipments. Everything else is yours to define.
The statuses with built-in behavior#
When a shipment reaches shipped, the plugin advances its Commerce order to the order status you configure under Shipments -> Settings (the auto-advance target). This is one-way: moving the shipment back out of shipped does not move the order back. Leave the target empty to disable it.
cancelled is written for you when an order enters a status listed under Shipments -> Settings -> General -> Order statuses that cancel shipments. Moving the order back out restores those shipments; see what the order’s status does to shipments.
No status requires any field. You can move a shipment to shipped with or without a tracking number; tracking, carrier, and service are always optional.
Derived ship date#
Shipment::getDateShipped() reads from the shipments_status_history table at read time, returning the first transition into shipped. It is not a stored column; the history table is the source of truth, and the getter is a convenience layer. It is instance-cached. Null when the shipment has never reached shipped.
Color palette#
Status::color() returns a Craft CP status-dot handle, used by Cp::statusLabelHtml() to render the pills on the element index and order tab.
| Value | Color |
|---|---|
new |
gray |
in_progress |
blue |
on_hold |
orange |
fulfilled |
teal |
shipped |
green |
cancelled |
red |
Changing the vocabulary#
You can’t from the CP. The list is source-code. If a real workflow needs a missing case, open a PR with the enum change plus its translation entry, color() entry, and a note in this doc. The intent: a stable, plugin-wide vocabulary lets emails, jobs, dashboards, and integration providers all agree on what each code means without coordination.