Order States and Statuses

Built-in Order States

// Magento\Sales\Model\Order
namespace Magento\Sales\Model\Order;

const STATE_NEW = 'new';
const STATE_PENDING_PAYMENT = 'pending_payment';
const STATE_PROCESSING = 'processing';
const STATE_COMPLETE = 'complete';
const STATE_CLOSED = 'closed';
const STATE_CANCELED = 'canceled';
const STATE_HOLDED = 'holded';
const STATE_PAYMENT_REVIEW = 'payment_review';

State Descriptions

State Transition Flow

// Order state transitions
namespace Magento\Sales\Model\Order;

// State transitions are triggered by actions:
// 1. new → pending_payment: Order placed, awaiting payment
// 2. pending_payment → processing: Payment confirmed
// 3. processing → complete: All items invoiced and shipped
// 4. processing → closed: Completed with refund
// 5. any → canceled: Order canceled
// 6. any → holded: Order held
// 7. processing → payment_review: Payment needs review

State Check Methods

$order = $this->orderRepository->get($orderId);

// Check current state
echo $order->getState(); // 'processing'

// Check if order can transition
if ($order->canInvoice()) {
    // Can still invoice items
}

if ($order->canShip()) {
    // Can still ship items
}

if ($order->canCreditmemo()) {
    // Can still refund items
}

// Check completion status
if ($order->getState() === \Magento\Sales\Model\Order::STATE_COMPLETE) {
    // Order fully processed
}

Creating Custom Statuses

// Create custom order status
namespace Vendor\Order\Service;

class CustomStatusManager
{
    public function __construct(
        private \Magento\Sales\Model\ResourceModel\Order\Status\Factory $statusFactory,
        private \Magento\Sales\Model\ResourceModel\Order\Status\CollectionFactory $statusCollectionFactory
    ) {}

    public function createStatus(
        string $code,
        string $label,
        string $state
    ): void {
        $status = $this->statusFactory->create();
        $status->setData([
            'status' => $code,
            'label' => $label,
            'state' => $state,
        ]);
        $status->save();

        // Assign to state
        $stateModel = $this->stateFactory->create()->load($state);
        $stateModel->assignStatus($code);
    }
}

Status Configuration

<!-- etc/di.xml -->
<config>
    <type name="Magento\Sales\Model\Order">
        <plugin name="custom_status" type="Vendor\Order\Plugin\OrderStatusPlugin"/>
    </type>
</config>

Status Plugin

namespace Vendor\Order\Plugin;

class OrderStatusPlugin
{
    public function beforeSetState(
        \Magento\Sales\Model\Order $order,
        string $state
    ): array {
        // Validate or modify state transition
        $currentState = $order->getState();

        // Custom transition rules
        $allowedTransitions = [
            'new' => ['pending_payment', 'canceled'],
            'pending_payment' => ['processing', 'canceled'],
            'processing' => ['complete', 'closed', 'canceled', 'holded'],
        ];

        if (!isset($allowedTransitions[$currentState]) ||
            !in_array($state, $allowedTransitions[$currentState])) {
            throw new \Magento\Framework\Exception\LocalizedException(
                __('Invalid state transition from %1 to %2', $currentState, $state)
            );
        }

        return [$state];
    }
}

State Machine Pattern

// State machine for order transitions
namespace Vendor\Order\StateMachine;

class OrderStateMachine
{
    private array $transitions = [
        'new' => ['pending_payment', 'canceled'],
        'pending_payment' => ['processing', 'canceled'],
        'processing' => ['complete', 'closed', 'canceled', 'holded', 'payment_review'],
        'complete' => ['closed', 'canceled'],
        'closed' => [],
        'canceled' => [],
        'holded' => ['processing', 'canceled'],
        'payment_review' => ['processing', 'canceled'],
    ];

    public function canTransition(
        string $fromState,
        string $toState
    ): bool {
        return isset($this->transitions[$fromState]) &&
               in_array($toState, $this->transitions[$fromState]);
    }

    public function transition(
        \Magento\Sales\Api\Data\OrderInterface $order,
        string $newState
    ): void {
        $currentState = $order->getState();

        if (!$this->canTransition($currentState, $newState)) {
            throw new \Magento\Framework\Exception\LocalizedException(
                __('Cannot transition from %1 to %2', $currentState, $newState)
            );
        }

        $order->setState($newState);
        $this->orderRepository->save($order);
    }
}

Automatic State Updates

// State updates happen automatically:
// 1. Order placed → new
// 2. Payment captured → processing
// 3. All items invoiced + shipped → complete
// 4. Refund issued → closed
// 5. Cancel action → canceled

// Manual state change
$order->setState(\Magento\Sales\Model\Order::STATE_HOLDED);
$order->addStatusHistoryComment('Order placed on hold for review');
$this->orderRepository->save($order);