How to Implement a Custom Order Status in Magento 2

If you're running a Magento 2 store, you know how important order statuses are for managing your sales process. By default, Magento 2 comes with a set of predefined order statuses like "Pending," "Processing," and "Complete." But what if your business has unique workflows that require custom order statuses? That's where implementing a custom order status comes into play.

In this guide, we'll walk you through the process of creating and implementing a custom order status in Magento 2. Whether you're a beginner or just need a refresher, we'll break it down step by step. Let's dive in!

Why Would You Need a Custom Order Status?

Custom order statuses can be incredibly useful for tailoring your store's workflow to your specific business needs. For example, you might want to add a status like "Awaiting Payment," "Ready for Pickup," or "Customs Clearance" to better reflect the stages of your order fulfillment process. This not only helps your team stay organized but also provides better transparency for your customers.

Step 1: Create a Custom Module

To implement a custom order status, you'll need to create a custom module. Don't worry—it's easier than it sounds! Here's how you can do it:

Create the Module Directory: Navigate to your Magento 2 root directory and create a new folder under app/code. For example, let's name it Magefine/CustomOrderStatus.
Create the registration.php File: Inside your module directory, create a file named registration.php and add the following code:

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Magefine_CustomOrderStatus',
    __DIR__
);

Create the module.xml File: Next, create a folder named etc inside your module directory, and within it, create a file named module.xml. Add the following code:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Magefine_CustomOrderStatus" setup_version="1.0.0"/>
</config>

This sets up the basic structure of your custom module.

Step 2: Define the Custom Order Status

Now that your module is set up, it's time to define your custom order status. Here's how:

Create the InstallData.php File: Inside your module directory, create a folder named Setup, and within it, create a file named InstallData.php. Add the following code:

<?php
namespace Magefine\CustomOrderStatus\Setup;

use Magento\Framework\Setup\InstallDataInterface;
use Magento\Framework\Setup\ModuleContextInterface;
use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Sales\Model\Order;
use Magento\Sales\Model\Order\StatusFactory;
use Magento\Sales\Model\ResourceModel\Order\StatusFactory as StatusResourceFactory;

class InstallData implements InstallDataInterface
{
    protected $statusFactory;
    protected $statusResourceFactory;

    public function __construct(
        StatusFactory $statusFactory,
        StatusResourceFactory $statusResourceFactory
    ) {
        $this->statusFactory = $statusFactory;
        $this->statusResourceFactory = $statusResourceFactory;
    }

    public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
    {
        $status = $this->statusFactory->create();
        $status->setData([
            'status' => 'custom_status',
            'label' => 'Custom Status'
        ]);

        $statusResource = $this->statusResourceFactory->create();
        $statusResource->save($status);

        $status->assignState(Order::STATE_PROCESSING, false, true);
    }
}

This code creates a new order status named "Custom Status" and assigns it to the "Processing" state. You can replace custom_status and Custom Status with your desired status code and label.

Step 3: Assign the Custom Status to an Order State

In Magento 2, order statuses are linked to order states. For example, the "Processing" state might have statuses like "Processing" and "Custom Status." To ensure your custom status is properly linked, you can use the following code snippet:

$status->assignState(Order::STATE_PROCESSING, false, true);

This line assigns your custom status to the "Processing" state. You can replace Order::STATE_PROCESSING with any other state, such as Order::STATE_NEW or Order::STATE_COMPLETE, depending on your needs.

Step 4: Deploy and Test

Once you've set up your custom order status, it's time to deploy and test it. Follow these steps:

Run Setup Upgrade: Open your terminal and navigate to your Magento 2 root directory. Run the following command to apply your changes:

php bin/magento setup:upgrade

Clear Cache: Clear the Magento cache to ensure your changes take effect:

php bin/magento cache:clean

Test the Custom Status: Go to your Magento admin panel, navigate to an order, and try assigning your custom status. You should see it listed in the status dropdown.

Step 5: Customize Further (Optional)

If you want to take your custom order status a step further, you can customize its appearance in the admin panel or add email notifications. For example, you can create a custom email template that gets sent when an order is assigned your custom status. To do this, you'll need to:

Create a new email template in the Magento admin panel.
Modify the sales_email_order_comment_template configuration to use your custom template.
Add logic in your module to trigger the email when the custom status is assigned.

Conclusion

Implementing a custom order status in Magento 2 is a powerful way to tailor your store's workflow to your business needs. By following the steps outlined in this guide, you can easily create and assign custom order statuses, improving both your team's efficiency and your customers' experience.

If you're looking for more advanced customization or need help with Magento 2 hosting, check out Magefine.com. We offer a range of extensions and hosting solutions to help you get the most out of your Magento store.

Happy coding!

How to Implement a Custom Order Status in Magento 2