Magento_Sales v2.4.x

Execution Flows

Detailed visualization of critical execution flows for order management in the Magento_Sales module. Understand how orders are placed, invoiced, shipped, and refunded through comprehensive step-by-step breakdowns.

Explore Flows Module Overview

Table of Contents

1

Order Placement Flow

Convert a customer's shopping cart (Quote) into a confirmed Order

Entry Points

Frontend Checkout
Magento\Checkout\Model\Type\Onepage::saveOrder()
Admin Order Create
Magento\Sales\Controller\Adminhtml\Order\Create\Save
REST API
POST /V1/carts/mine/order
GraphQL
mutation { placeOrder(input: {...}) }

Execution Steps

1

Quote Submission

Magento\Quote\Model\QuoteManagement → submit()

Validates the quote and initiates the conversion process to an order entity.

QuoteManagement.php 
public function submit(QuoteEntity $quote, $orderData = [])
{
    // 1. Validate quote
    $this->validateQuote($quote);

    // 2. Trigger quote_submit_before event
    $this->eventManager->dispatch('checkout_submit_before', ['quote' => $quote]);

    // 3. Convert quote to order
    $order = $this->quoteToOrderConverter->convert($quote);

    // 4. Save order
    $order = $this->orderRepository->save($order);

    // 5. Trigger checkout_submit_all_after event
    $this->eventManager->dispatch('checkout_submit_all_after',
        ['order' => $order, 'quote' => $quote]);

    return $order->getId();
}
2

Quote to Order Conversion

Magento\Quote\Model\Quote\Address\ToOrder

Creates order entities from quote data including items, addresses, and payment information.

Entities Created
  • sales_order - Main order record
  • sales_order_item - Order items from quote items
  • sales_order_address - Billing/shipping addresses
  • sales_order_payment - Payment information
3

Order Persistence

Magento\Sales\Model\OrderRepository → save()

Persists order data to database tables and updates admin grid for display.

Database Table Purpose
sales_order Main order record
sales_order_grid Admin grid display optimization
sales_order_status_history Order status change log
4

Order State Initialization

Initial State
new
Initial Status
pending
5

Event Triggers

Multiple events are dispatched throughout the order placement flow for extensibility.

checkout_submit_before
Before order creation
sales_model_service_quote_submit_before
Quote submission start
sales_model_service_quote_submit_success
Order created successfully
checkout_submit_all_after
All processing complete

Common Issues

  • Quote validation failures: Missing required fields (email, address)
  • Payment authorization failures: Declined cards, gateway timeouts
  • Inventory reservation failures: Out of stock items
  • Database deadlocks: High concurrency during sales
6

Order State/Status Transitions

Understand the order lifecycle and valid state machine transitions

States (System-Level)

Immutable system states that control order behavior

  • STATE
    new
    Order created, payment pending
  • STATE
    pending_payment
    Awaiting payment authorization
  • STATE
    processing
    Payment captured, fulfillment in progress
  • STATE
    complete
    Fully shipped/delivered
  • STATE
    closed
    Completed with refunds or cancelled with refunds
  • STATE
    canceled
    Cancelled before fulfillment
  • STATE
    holded
    On hold (manual admin action)

Statuses (Display Labels)

Customizable labels shown to merchants and customers

  • pending
    New order, payment pending
  • processing
    Being processed
  • complete
    Completed
  • canceled
    Cancelled
  • on_hold
    On administrative hold
  • Custom Statuses
    Merchants can create additional statuses

Valid State Transitions

new processing (invoice created)
new canceled (order cancelled)
processing complete (fully shipped)
complete closed (refund issued)

Performance Considerations

Order Grid Performance Issue

Large order volumes can slow down admin grid queries significantly.

Solution: Add Indexes
ALTER TABLE sales_order_grid
ADD INDEX idx_customer_email (customer_email);

ALTER TABLE sales_order_grid
ADD INDEX idx_created_at (created_at);

Order Load Optimization

Use repository pattern with search criteria for efficient order loading.

Optimized Order Loading 
// Use repository with field filtering
$searchCriteria = $this->searchCriteriaBuilder
    ->addFilter('increment_id', $orderNumber)
    ->create();

$orders = $this->orderRepository
    ->getList($searchCriteria);