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_idOrder ID (integer)
$old_statusPrevious status (string)
$new_statusNew status (string)
$orderWC_Order object
SourceWooCommerce 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).