Magento: Observer for order state is complete

Magento: Observer for order state is complete

July 1, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento: Observer for order state is complete

Handling Magento Order Completion: Observer Best Practices

In Magento, managing order state transitions is crucial for triggering post-order actions like commission calculation or agent payouts. When developing your custom commission module, you’re right to focus on the order’s ‘complete’ status rather than the initial placement or shipment events.

Identifying the Right Event Observer

The key to this implementation lies in finding the appropriate event observer that captures the exact moment when an order transitions to a completed state. Let me guide you through the most reliable approach:

1. sales_order_save_after Event

While Magento doesn’t provide a dedicated ‘sales_order_complete’ event, we can utilize the sales_order_save_after event with a custom condition to achieve this.

In your observer file, implement a condition that checks if the order status has just changed to ‘complete’. Here’s a basic example:

$order->getOrigData('status') != $order->getStatus()

This checks whether the original and current status values differ. If they do, it implies the status has been updated.

2. sales_order_save_before Observer

An alternative approach is to use the sales_order_save_before event. In this case, you’d need to compare the new order status with its previous value before saving:

$order->getOrigData('status') != $order->getStatus()

Implementation Steps

  1. Create a custom module using Magento’s best practices for module structure.
  2. Declare your observer in the etc/events.xml file:
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="sales_order_save_after">
        <observer name="your_module_name_observer" instance="Your\Module\Observer\OrderSaveAfterObserver"/>
    </event>
</config>
  1. Implement your observer class:
namespace Your\Module\Observer;

use Magento\Framework\Event\ObserverInterface;
use Magento\Sales\Model\ResourceModel\Order as OrderResourceModel;

class OrderSaveAfterObserver implements ObserverInterface
{
    private $orderResourceModel;

    public function __construct(OrderResourceModel $orderResourceModel)
    {
        $this->orderResourceModel = $orderResourceModel;
    }

    public function execute(\Magento\Framework\Event\Observer $observer)
    {
        $order = $observer->getData('order');
        if ($order->getOrigData('status') != $order->getStatus() && $order->getStatus() == 'complete') {
            // Your commission calculation logic here
        }
    }
}
  1. Run setup:upgrade and clear cache to apply the changes.

Why This Works

This approach ensures that your agent payouts are triggered only when an order transitions to a complete state, regardless of the number of shipments associated with it. It is a robust solution that adheres to Magento’s event-driven architecture without resorting to polling or cron jobs.

Remember that performance optimization is crucial when handling large numbers of orders. Consider implementing pagination if your commission calculations are resource-intensive.

Conclusion

In Magento 2, capturing order completion events requires a strategic approach using the sales_order_save_after or sales_order_save_before events. By implementing a custom observer with a conditional check for status changes, you can ensure that your agent payouts and commission calculations occur at the precise moment when an order reaches its final state.

For more detailed guidance on Magento 2 development best practices, I recommend visiting https://laravelcompany.com/blog/magento-development-best-practices to stay up-to-date with the latest trends and techniques.

Extensions Orders

Our network