How to Send a Custom Email When a WooCommerce Order Status Changes
You can send a custom email when a WooCommerce order status changes in two ways: build a workflow on a visual canvas in about five minutes with no code, or register a custom WC_Email class using the woocommerce_order_status_changed hook. Neither approach requires touching your theme files or installing a bulky extension. This tutorial walks through both methods so you can choose the one that fits your setup.
WooCommerce sends built-in emails for a handful of statuses like Processing, Completed and Refunded. The moment you add a custom status, such as “Ready for Pickup” or “Awaiting Inspection”, WooCommerce goes silent. That gap is where orders fall through and customers stop trusting your store.
We tested both methods on WordPress 6.5 with WooCommerce 8.9. The no-code path takes roughly 5 minutes to configure. The PHP path takes 20 to 40 minutes if you have never written a WC_Email subclass before, but it gives you full template control and zero plugin dependencies.
Which Method Should You Use?
| Situation | Best method | Approximate setup time |
|---|---|---|
| One or two statuses, non-developer | Visual workflow builder | 5 minutes |
| Multiple statuses with different logic per status | Visual workflow builder with branching | 15 to 30 minutes |
| Full HTML template control, no plugin dependencies | PHP hook + WC_Email subclass | 20 to 40 minutes |
| Send to admin AND customer with different content | Visual workflow builder (two actions) | 10 minutes |
| Also need to tag CRM, update Sheets, or notify Slack | Visual workflow builder | Adds 2 minutes per extra action |
If you are running more than three custom statuses or need to chain additional actions after the email, the no-code path will save you hours of maintenance every time WooCommerce updates its email API. The PHP path is the right call when you need pixel-perfect HTML templates or cannot add another plugin.
Method 1: No-Code Workflow Builder (Recommended for Most Stores)
This method uses the free Krom Automation plugin from the WordPress.org plugin directory. The free version includes both WooCommerce triggers you need: Order Created and Order Completed. The Order Status Changed trigger, which fires on any transition you define, is included with no paywall.
Step 1: Install the Plugin
Go to Plugins > Add New in your WordPress admin. Search for “Krom Automation” and click Install, then Activate.
You will see a new Krom Automation menu item in the sidebar. If you have not done this before, the installation guide covers the full process including server requirements.
Step 2: Create a New Workflow
Click Krom Automation > Workflows > Add New. You will land on the visual canvas, a drag-and-drop builder.
You will see a blank Start node already placed. Give the workflow a name in the top-left field, something like “Ready for Pickup Email”.
Step 3: Set the Trigger
Click the Start node and choose Order Status Changed from the WooCommerce trigger group. You will see two dropdowns: From Status and To Status.
Set From to “Processing” and To to your custom status, for example “Ready for Pickup”. If you want this email to fire regardless of the previous status, leave From set to “Any”.
Setting “From Status” to Any is fine for most stores. Setting it to a specific status prevents the email firing when you manually correct a mis-entered status, which is a subtle but important distinction.
Step 4: Add the Send Email Action
Click the plus icon below the trigger node to add an action. Select Send Email from the Email group. You will see fields for To, Subject, and Body.
- To: Enter
{{order.billing_email}}to send to the customer. Enter a fixed address likeorders@yourstore.comto notify your team. Add both in separate action nodes if you need both. - Subject: Something like “Your order #{{order.number}} is ready for pickup”.
- Body: Plain text or HTML. Use merge tags to inject live order data. The full list of available merge tags is documented in the merge tags reference.
Merge tags pull data directly from the order at the moment the trigger fires. {{order.total}}, {{order.billing_first_name}}, {{customer.email}} and {{order.line_items}} are the ones most stores use in order emails. Each tag resolves to the live value with no extra configuration.
Step 5: Test Before Publishing
Click the Simulate button in the top toolbar. The simulator runs the workflow against a real order ID you supply, showing you exactly what each action would do without sending any actual emails.
This is a dry run with zero side effects. The simulator documentation explains how to read the output and spot misconfigured merge tags before they reach a real customer.
Once the simulation looks right, toggle the workflow from Draft to Active and save. The next time an order moves to your target status, the email fires automatically in the background via Action Scheduler, so it does not slow down the status-change request.
Step 6: Add Conditional Logic (Optional)
If you want different email content depending on order value, shipping method or customer role, add a Condition node between the trigger and the action. Set the Yes path to your premium customer email and the No path to the standard one. The conditions and branching documentation covers every available operator.
A workflow that sends different emails to wholesale and retail customers based on order total takes about eight minutes to build. Writing that logic in PHP takes significantly longer and breaks on every WooCommerce major version.
Method 2: PHP Hook and WC_Email Subclass
This path requires no plugin beyond WooCommerce itself. You will use the woocommerce_order_status_changed action hook and register a custom email class. WooCommerce’s own documentation on email configuration and the WordPress plugin hooks reference are worth bookmarking before you start.
Step 1: Register the Custom Status
If you have not already registered your custom status, add the following to your theme’s functions.php or a site-specific plugin. Using a site-specific plugin is safer because theme updates will not wipe your code.
add_action( 'init', function() {
register_post_status( 'wc-ready-pickup', array(
'label' => 'Ready for Pickup',
'public' => true,
'exclude_from_search' => false,
'show_in_admin_all_list' => true,
'show_in_admin_status_list' => true,
'label_count' => _n_noop( 'Ready for Pickup (%s)', 'Ready for Pickup (%s)' ),
) );
} );
add_filter( 'wc_order_statuses', function( $statuses ) {
$statuses['wc-ready-pickup'] = 'Ready for Pickup';
return $statuses;
} );
Step 2: Create the WC_Email Subclass
Create a file called class-wc-email-ready-pickup.php and place it in your plugin or a dedicated /includes/emails/ folder. The class must extend WC_Email.
class WC_Email_Ready_Pickup extends WC_Email {
public function __construct() {
$this->id = 'ready_pickup';
$this->title = 'Ready for Pickup';
$this->description = 'Sent when an order is marked Ready for Pickup.';
$this->heading = 'Your order is ready!';
$this->subject = 'Order #{order_number} is ready for pickup';
$this->template_html = 'emails/ready-pickup.php';
$this->template_plain = 'emails/plain/ready-pickup.php';
$this->template_base = plugin_dir_path( __FILE__ ) . 'templates/';
$this->placeholders = array(
'{order_number}' => '',
'{order_date}' => '',
);
parent::__construct();
}
public function trigger( $order_id, $order = false ) {
if ( $order_id && ! is_a( $order, 'WC_Order' ) ) {
$order = wc_get_order( $order_id );
}
if ( is_a( $order, 'WC_Order' ) ) {
$this->object = $order;
$this->recipient = $order->get_billing_email();
$this->placeholders['{order_number}'] = $order->get_order_number();
$this->placeholders['{order_date}'] = wc_format_datetime( $order->get_date_created() );
}
if ( $this->is_enabled() && $this->get_recipient() ) {
$this->send( $this->get_recipient(), $this->get_subject(), $this->get_content(), $this->get_headers(), $this->get_attachments() );
}
}
public function get_content_html() {
return wc_get_template_html( $this->template_html, array(
'order' => $this->object,
'email_heading' => $this->get_heading(),
'email' => $this,
), '', $this->template_base );
}
public function get_content_plain() {
return wc_get_template_html( $this->template_plain, array(
'order' => $this->object,
'email_heading' => $this->get_heading(),
'email' => $this,
), '', $this->template_base );
}
}
Step 3: Register the Email Class with WooCommerce
WooCommerce collects all email classes via the woocommerce_email_classes filter. Add your class to the array so WooCommerce knows it exists and can display it in WooCommerce > Settings > Emails.
add_filter( 'woocommerce_email_classes', function( $email_classes ) {
require_once plugin_dir_path( __FILE__ ) . 'includes/emails/class-wc-email-ready-pickup.php';
$email_classes['WC_Email_Ready_Pickup'] = new WC_Email_Ready_Pickup();
return $email_classes;
} );
Step 4: Hook the Trigger to the Status Change
Use the woocommerce_order_status_changed hook to call your email’s trigger() method. This hook fires after every status transition and passes the order ID, the old status slug and the new status slug.
add_action( 'woocommerce_order_status_changed', function( $order_id, $old_status, $new_status ) {
if ( 'ready-pickup' === $new_status ) {
$email_class = WC()->mailer()->get_emails()['WC_Email_Ready_Pickup'];
$email_class->trigger( $order_id );
}
}, 10, 3 );
Step 5: Create the Email Templates
WooCommerce expects HTML and plain-text template files. Create templates/emails/ready-pickup.php and templates/emails/plain/ready-pickup.php inside your plugin.
Copy the structure from WooCommerce’s own woocommerce/templates/emails/customer-processing-order.php as a starting point. That keeps your email visually consistent with the rest of WooCommerce’s transactional email set.
What the Guides Leave Out: Hidden Costs and Real Failure Modes
Every tutorial shows you the happy path. Here is what breaks in production.
- WP-Cron on low-traffic sites: The no-code workflow uses Action Scheduler, which relies on WP-Cron. If your store gets fewer than roughly 20 visits per hour overnight, emails scheduled during quiet periods may fire late by 30 to 90 minutes. Fix this by configuring a real server cron job to call
wp-cron.phpevery five minutes. The WordPress developer docs on WP-Cron explain the setup. - PHP method breaks on major WooCommerce updates:
WC_Emailinternals change between major versions. Theget_content_html()method signature changed between WooCommerce 7 and 8. Budget 30 to 60 minutes of review time after each major WooCommerce update if you go the PHP route. - Sending to admin AND customer: WooCommerce’s built-in emails send to one recipient per class. For the PHP method, you need a second email class or a second
wp_mail()call inside the same trigger. With the visual builder, you add a second Send Email action node pointing to your admin address. That takes about 90 seconds. - Custom statuses disappearing after plugin deactivation: If you used a third-party “custom order status” plugin to register the status and later deactivate it, all orders in that status lose their status label. The status slug stays in the database but WooCommerce cannot read it. Keep status registration in your own code, not in a plugin you might remove.
- Emails landing in spam: Neither method fixes deliverability. If your server’s PHP
mail()function is not authenticated, the email will likely land in spam regardless of content. Use an SMTP plugin or a transactional email service like Postmark or SendGrid. The WooCommerce email FAQ covers SMTP configuration options.
Deliverability is not a WooCommerce problem. It is a mail server problem. Fixing the email trigger without fixing the sending infrastructure means perfectly written emails end up in spam folders, which is worse than no email at all.
Going Further: What Else You Can Do on Order Status Change
Once you have the email working, the same trigger can power additional actions in the same workflow. These are common extensions stores add after getting the basic email right.
- Tag the customer in FluentCRM or ActiveCampaign when an order reaches a specific status, so follow-up sequences fire automatically.
- Add a row to Google Sheets for every fulfilled order, giving the ops team a live fulfilment log without dashboard access.
- Post a message to a Slack or Discord channel when a high-value order completes, so the team knows immediately.
- Generate a unique coupon and email it to the customer after their first completed order. We covered this exact pattern in the guide on sending a coupon after a customer’s first WooCommerce order.
- Change the customer’s WordPress user role after purchase, which is documented step by step in how to change a user role after a WooCommerce purchase.
All of these actions sit on the same canvas as your email node. You are not building separate automations for each one. That matters for maintenance: one workflow to audit rather than five separate plugins each handling one piece of the same event.
If your store uses WooCommerce Subscriptions, the same pattern applies to subscription events. The WooCommerce Subscriptions integration documentation lists the available triggers and action examples.
Other Tools Worth Knowing About
Pollify is wpRigel’s Gutenberg-native poll and survey plugin. Polls are built as real blocks inside the editor, so there are no shortcodes to paste and no separate interface to learn. If you collect post-purchase feedback on order confirmation pages, it integrates naturally with the block editor.
Commandify is a command palette for the WordPress admin. Press Cmd or Ctrl plus K to search orders, products and customers, change order status, apply coupons or resend order emails, all without navigating through menus. It is the only WordPress command palette with real WooCommerce order management commands built in.
Frequently Asked Questions
Why isn’t WooCommerce sending an email when I change the order status manually?
WooCommerce only sends emails for the statuses it knows about by default: Pending, Processing, On Hold, Completed, Cancelled, Refunded and Failed. Custom statuses get no email unless you explicitly configure one using either the PHP method above or a workflow tool. Manually changing a status in the admin does fire the woocommerce_order_status_changed hook, so the PHP method will work for manual changes as long as the hook is registered correctly.
Can I send different email content for each custom order status?
Yes. With the PHP approach, create one WC_Email subclass per status and register each separately.
With the visual builder, create one workflow per status or use a single workflow with conditional branching on the “To Status” value. The branching approach keeps your workflow count low when you have four or more custom statuses.
How do I send the order status change email to both the admin and the customer?
In the PHP approach, add a second wp_mail() call inside the same trigger function, or create a second email class. In the visual builder, add two Send Email action nodes to the same workflow: one with {{order.billing_email}} as the recipient and one with your admin address. Both fire in the same workflow run.
How do I resend a WooCommerce order status email manually?
Go to the order edit screen in WooCommerce, scroll to the Order Actions meta box on the right, and select “Resend [email name]” from the dropdown. Click the arrow button to trigger it.
If your custom email does not appear in that dropdown, the email class is not registered correctly with the woocommerce_email_classes filter. With the visual builder, you can manually trigger a workflow from the execution history panel by selecting the order and clicking Re-run.
Do custom WooCommerce order status emails work with HPOS (High-Performance Order Storage)?
Yes, as long as you use wc_get_order() to retrieve the order object rather than querying the wp_posts table directly. Both methods in this tutorial use wc_get_order(), so they are compatible with HPOS. WooCommerce’s official guidance on HPOS compatibility is in their developer documentation.
Next Steps
If you are starting from scratch and want the fastest path to a working custom order status email, install the free plugin from WordPress.org and follow Method 1. You will have a live workflow in under ten minutes with no code to maintain. If you need full template control or cannot add a plugin, Method 2 gives you everything WooCommerce exposes natively.
Either way, fix your SMTP setup first. The best-configured email trigger in the world does nothing if the mail lands in spam.