How to Create a Custom Order Status in WooCommerce (Step-by-Step Guide)

Customizing WooCommerce is a powerful way to meet specific business needs. In this guide, we will walk you through the process of adding a custom order status and customizing its email templates. With a few simple steps, you can integrate a custom order status and use it in your WooCommerce store.

Step 1: Add a Custom Order Status to WooCommerce

To begin, you’ll need to register your custom order status using the register_post_status function. Add this code to your theme’s functions.php file or in a custom plugin:

// Add custom order status
function add_custom_order_status() {
    register_post_status( 'wc-custom-status', array(
        'label'                     => _x( 'Custom Status', 'Order status', 'your-text-domain' ),
        'public'                    => true,
        'exclude_from_search'       => false,
        'show_in_admin_all_list'    => true,
        'show_in_admin_status_list' => true,
        'label_count'               => _n_noop( 'Custom Status <span class="count">(%s)</span>', 'Custom Status <span class="count">(%s)</span>', 'your-text-domain' )
    ) );
}
add_action( 'init', 'add_custom_order_status' );

Step 2: Add Your Custom Order Status to the Admin Filter Dropdown

Make sure your custom order status is visible in the order admin filter dropdown by adding this code using the wc_order_statuses filter:

// Add custom order status to admin filter dropdown
function add_custom_order_status_to_filter( $order_statuses ) {
    $order_statuses['wc-custom-status'] = _x( 'Custom Status', 'Order status', 'your-text-domain' );
    return $order_statuses;
}
add_filter( 'wc_order_statuses', 'add_custom_order_status_to_filter' );

Step 3: Register Custom Email Action for Your Custom Order Status

Next, register a custom email action for your custom order status. This is done using the woocommerce_email_actions filter:

// Register custom email action for custom order status
function add_custom_email_action( $email_actions ) {
    $email_actions[] = 'woocommerce_order_status_wc-custom-status';
    return $email_actions;
}
add_filter( 'woocommerce_email_actions', 'add_custom_email_action' );

Step 4: Create a Custom Email Class for the Custom Order Status

Now, let’s define the custom email class. This class extends WC_Email and will be responsible for sending emails when the order status changes to the custom status. Save this class in a file like custom-new-order-email.php:

// custom-new-order-email.php
class Custom_New_Order_Email extends WC_Email {
    /**
     * Constructor.
     */
    public function __construct() {
        $this->id             = 'custom_new_order';
        $this->title          = __( 'Custom New Order', 'your-text-domain' );
        $this->description    = __( 'Custom new order emails are sent when the order status is changed to the custom order status.', 'your-text-domain' );
        $this->heading        = __( 'Custom New Order', 'your-text-domain' );
        $this->subject        = __( 'New Order: #{order_number}', 'your-text-domain' );
        $this->template_html  = 'emails/custom-new-order.php';
        $this->template_plain = 'emails/plain/custom-new-order.php';
        $this->template_base  = plugin_dir_path( __FILE__ ); // Path to your custom-new-order-email.php file directory
        $this->placeholders  = array(
            '{order_number}' => '',
            // Add more placeholders if needed
        );

        // Call parent constructor
        parent::__construct();

        // Other settings, hooks, and filters can be added here
    }

    /**
     * Trigger.
     *
     * @param int $order_id The order ID.
     */
    public function trigger( $order_id ) {
        // Get order object
        $this->object = wc_get_order( $order_id );

        // Set email recipient
        $this->recipient = $this->object->get_billing_email();

        // Set email heading and subject
        $this->placeholders['{order_number}'] = $this->object->get_order_number();
        $this->heading                      = apply_filters( 'woocommerce_email_heading_' . $this->id, $this->heading, $this->object );
        $this->subject                      = apply_filters( 'woocommerce_email_subject_' . $this->id, $this->subject, $this->object );

        // Call parent trigger to send the email
        parent::trigger( $order_id );
    }
}

Step 5: Hook the Custom Email Class to WooCommerce

Lastly, you need to hook your custom email class into WooCommerce using the woocommerce_email_classes filter:

// Hook custom email class to WooCommerce
function add_custom_email_class( $email_classes ) {
    require_once 'path/to/custom-new-order-email.php'; // Replace with the actual path to your custom-new-order-email.php file
    $email_classes['Custom_New_Order_Email'] = new Custom_New_Order_Email();
    return $email_classes;
}
add_filter( 'woocommerce_email_classes', 'add_custom_email_class' );

Conclusion

With these steps, you’ve successfully added a custom order status in WooCommerce and configured a custom email template for it. This email will be triggered when the order status is set to your new custom status. You can further customize the email content, subject, and recipient information as needed.

Important: Always use a child theme or custom plugin to add your custom code. Testing the changes thoroughly before deploying to a live site is recommended.

For more advanced customizations and tips, you can refer to the official WooCommerce Documentation on Customizing Emails.