woocommerce_order_status_changed
WooCommerce fires woocommerce_order_status_changed when an existing order transitions from one status to another. This action provides the order ID, both status slugs, and the order object. Register four accepted arguments if your callback needs them all:
$order_id | Order ID (integer) |
|---|---|
$old_status | Previous status (string) |
$new_status | New status (string) |
$order | WC_Order object |
| Source | WooCommerce order status-transition handling |
Log a transition to completed
add_action( 'woocommerce_order_status_changed', function ( $order_id, $old_status, $new_status, $order ) {
if ( 'completed' === $new_status ) {
$order->add_order_note( 'Order reached completed status.' );
}
}, 10, 4 );
This adds a private order note when the order enters completed. Status arguments use slugs such as processing and completed, without the wc- prefix. If an order leaves and later returns to completed, another note is added. Test order transitions on a staging store before introducing effects beyond notes.
Choose the right lifecycle event
This is not a general order-creation hook. WooCommerce calls it only when a previous status exists; it can run after changes made by administrators or programmatically, with no customer viewing a checkout page. A status of completed also does not independently prove that a particular payment was captured. External notifications or fulfillment actions need protection against duplicate processing and an event suited to their purpose.
For order metadata, use $order->get_meta() and $order->update_meta_data(), saving the order when needed, instead of writing directly to WordPress post meta. The WooCommerce order APIs support High-Performance Order Storage (HPOS).