Rule 1: everything goes through WooCommerce
The plugin does not draw its own dropdowns or lists. For each status you create it does exactly two things, and WooCommerce does the rest:
- On
init, it registers a WordPress post status namedwc-plus your slug (for examplewc-awaiting-stock), with your label and an "(count)" label for the status filter links. The status is not public, and it is listed in the admin "All" view and the status links. - It adds the status to WooCommerce's
wc_order_statusesfilter — the single list WooCommerce reads for the order screen's Status dropdown, the orders list, the status filter and anything else that lists order statuses.
Because WooCommerce reads the status from its own list, moving an order into it is an ordinary WooCommerce status change: it writes the usual order note, fires WooCommerce's woocommerce_order_status_{slug} and woocommerce_order_status_changed actions, and other plugins can react to it.
What a custom status does not do on its own: WooCommerce does not treat it as paid, does not reduce or restore stock when an order moves into it, and sends none of its own emails for it. Moving a Processing order to "Awaiting stock" leaves its stock where it was.
Bulk actions
On both orders screens (HPOS and classic), Bulk actions gets a Change status to … entry for each custom status. Applying one calls WooCommerce's update_status() on each selected order with the note "Status changed in bulk."
The actions are named mark_ plus the slug, the same pattern WooCommerce uses for its own. An action called mark_… that is not one of your custom statuses is passed on untouched, so another plugin's bulk actions keep working.
Rule 2: a slug is permanent, and orders are history
An order stores its status as the slug. The plugin never rewrites orders:
- Removing a status leaves every order in it alone. Those orders keep
wc-yourslugin the database. While the status is gone WooCommerce does not list it, so move such orders to another status first, or add the status back with the same slug and they reappear. - A slug cannot be changed once a status is saved: the settings screen shows it as text and keeps the stored slug whatever is posted beside it. A new slug is a new status.
- Uninstalling deletes only the plugin's own options.
Rewriting order history is never the plugin's call.
Badge colours — Full edition
On every admin page, the plugin adds a small inline stylesheet with one rule per status:
.order-status.status-awaiting-stock { background: #f59e0b; color: #1f2937; }
.order-status.status-{slug} is the class WooCommerce gives a status badge on the orders list. The text colour is worked out from the colour's perceived brightness, so a yellow badge gets dark text and a navy one gets white.
Customer emails — Full edition
When an order changes status (WooCommerce's woocommerce_order_status_changed action), the plugin checks whether the new status is one of yours with Email the customer on. If so:
- It reads the billing email; an order without one sends nothing.
- It fills the placeholders in your subject and body (or the defaults). The values filled into the body are escaped, the body is given paragraphs with
wpautop(), and the subject is stripped to plain text. - It passes the message through the
gmos_emailfilter, which can change it or cancel it. - It sends it with
wp_mail()as HTML (Content-Type: text/html).
The email goes out every time an order enters the status — so moving an order out and back in sends it again.
Worked example (full edition)
A made-to-order furniture shop adds three statuses:
| Label | Slug | Color | |
|---|---|---|---|
| In the workshop | in-workshop |
#2563eb |
On — "Your table is being made" |
| Ready to deliver | ready-to-deliver |
#16a34a |
On |
| Awaiting fabric | awaiting-fabric |
#f59e0b |
Off |
- A paid order arrives as Processing. The shop selects it with the morning's other orders and applies Change status to In the workshop.
- Each customer receives "Your table is being made", the badges turn blue, and each order gets the note "Status changed in bulk."
- One order is waiting for fabric; it is moved to Awaiting fabric (amber, no email). When the fabric arrives it goes back to In the workshop — and that customer receives the workshop email again.
- When a table is finished the order moves to Ready to deliver, then to Completed, which sends WooCommerce's own completed-order email.
