Magento_Sales Architecture | Magento Core Documentation

Quick Stats

861

Total Nodes

243

Total Edges

6

Dependencies

2.4.x

Compatible

Module Overview

The Magento_Sales module is the core order management system in Magento, responsible for the complete lifecycle of sales transactions from order placement through fulfillment and refunds.

What Magento_Sales Does

→ Order Management: Order placement, state/status management, order history
→ Invoice Management: Invoice creation, partial invoicing, payment capture
→ Shipment Management: Shipment creation, tracking, partial shipping
→ Credit Memo Management: Refunds, returns, credit memo creation
→ Transaction Management: Payment transaction records and history
→ Email Notifications: Order, invoice, shipment, and creditmemo emails
→ Grid Management: Admin grids for orders, invoices, shipments, creditmemos
→ REST/SOAP APIs: Complete service contract implementation for external integrations
→ State Machine: Complex order status and state workflows
→ Totals Calculation: Order totals, tax, shipping, discounts

Position in Magento Ecosystem

Architectural Layer: Core Business Module

The Sales module sits at the core business layer of Magento's architecture, bridging checkout (Quote) with fulfillment and integrating with payment, shipping, tax, and customer modules.

Direct Dependencies

→ Magento_Eav: Order and address entities may use EAV for custom attributes
→ Magento_Customer: Customer association, email synchronization
→ Magento_Payment: Payment method integration, authorization/capture
→ Magento_Catalog: Product information for order items
→ Magento_Store: Multi-store order management
→ Magento_Directory: Country/region data for addresses

Key Dependent Modules

Modules that depend on Magento_Sales:

• Magento_Checkout

• Magento_Shipping

• Magento_Tax

• Magento_Backend

• Magento_Reports

• Magento_SalesRule

• Magento_Downloadable

• Magento_GiftMessage

Service Contracts (API Layer)

The Sales module is the largest service contract implementation in Magento, exposing 82 interfaces for order management operations.

Core Management Interfaces

1. OrderRepositoryInterface

Purpose: Main CRUD interface for order entities

Location: Magento\Sales\Api\OrderRepositoryInterface

Implementation: Magento\Sales\Model\OrderRepository

Key Methods:

save(OrderInterface $order): OrderInterface
get($id): OrderInterface
getList(SearchCriteriaInterface $searchCriteria): OrderSearchResultsInterface
delete(OrderInterface $order): bool
deleteById($id): bool

2. OrderManagementInterface

Purpose: High-level order operations (place order, cancel, hold, etc.)

Location: Magento\Sales\Api\OrderManagementInterface

Implementation: Magento\Sales\Model\Service\OrderService

Key Methods:

place(OrderInterface $order): OrderInterface
cancel($id): bool
hold($id): bool
unHold($id): bool
addComment($id, OrderStatusHistoryInterface $statusHistory): bool
notify($id): bool
getStatus($id): string

3. InvoiceRepositoryInterface

Purpose: CRUD operations for invoices

Location: Magento\Sales\Api\InvoiceRepositoryInterface

4. ShipmentRepositoryInterface

Purpose: CRUD operations for shipments

Location: Magento\Sales\Api\ShipmentRepositoryInterface

5. CreditmemoRepositoryInterface

Purpose: CRUD operations for credit memos (refunds)

Location: Magento\Sales\Api\CreditmemoRepositoryInterface

Database Schema

Primary Tables

sales_order

Purpose: Main order data

Column	Type	Description
`entity_id`	INT (PK)	Order ID
`increment_id`	VARCHAR(50)	Human-readable order number
`customer_id`	INT	FK to customer_entity
`state`	VARCHAR(32)	Order state (new, processing, complete, etc.)
`status`	VARCHAR(32)	Order status (configurable)
`grand_total`	DECIMAL(20,4)	Order total in order currency

Important: State and status are separate. States are fixed (code constants), statuses are configurable (database values).

sales_order_item

Purpose: Individual line items in order

Key columns: item_id (PK), order_id, product_id, sku, name, qty_ordered, qty_invoiced, qty_shipped, qty_refunded, price

sales_invoice

Purpose: Invoice records

Key concept: Multiple invoices can exist per order (partial invoicing).

sales_shipment

Purpose: Shipment records

Includes: shipment items, tracking numbers, shipping labels (BLOB)

sales_creditmemo

Purpose: Credit memo (refund) records

Includes: refund items, adjustment amounts, refund totals

Grid Tables

Magento 2.3+ uses dedicated grid tables for performance:

• sales_order_grid - Flattened order data for admin grid

• sales_invoice_grid - Flattened invoice data

• sales_shipment_grid - Flattened shipment data

• sales_creditmemo_grid - Flattened credit memo data

Key Concept: Grid tables are synchronized via observers listening to *_process_relation events. They contain denormalized data for fast admin grid rendering.

Order State Machine

States vs. Statuses

State (internal, immutable)

→ Fixed PHP constants
→ Used in business logic
→ Cannot be created/deleted

Status (external, configurable)

→ Database-driven
→ Can be created/customized
→ Mapped to states

Core Order States

State	Constant	Description
`new`	Order::STATE_NEW	Order created, not yet processed
`pending_payment`	Order::STATE_PENDING_PAYMENT	Awaiting payment confirmation
`processing`	Order::STATE_PROCESSING	Order is being fulfilled
`complete`	Order::STATE_COMPLETE	Order fully fulfilled
`canceled`	Order::STATE_CANCELED	Order canceled
`holded`	Order::STATE_HOLDED	Order on hold

Extension Points

Plugin Intercept Points

The module provides 16 plugins for customization.

Critical Intercept Points:

1. Controller Authentication Plugins (10 plugins) - Frontend order view authentication
2. Order Repository Plugins - Order CRUD operations
3. Grid Export Filters - Admin grid export customization
4. Address Update Handler - Order address modifications
5. Invoice Service - Transaction comment addition after capture

Event-Based Extension Points

The module dispatches 19 core events:

Order Lifecycle Events:

→ sales_order_place_after (critical for integrations)
→ sales_order_save_before
→ sales_order_save_after
→ sales_order_process_relation (triggers grid sync)

Invoice Events:

→ sales_order_invoice_save_before
→ sales_order_invoice_save_after
→ sales_order_invoice_process_relation (grid sync trigger)

Shipment Events:

→ sales_order_shipment_save_before
→ sales_order_shipment_save_after
→ sales_order_shipment_process_relation (grid sync trigger)

Performance Considerations

Caching Strategy

No FPC for Orders: Order data is always dynamic. No full page caching for order pages.
Grid Table Optimization: Dedicated grid tables for fast admin rendering with asynchronous grid indexing (optional).
Email Queue: Asynchronous email sending (optional) reduces order placement time via background cron processing.

Database Performance

Key Indexes:

• Order: increment_id, customer_id, email, created_at, status, state
• Grid tables: All filterable/sortable columns
• Item tables: order_id, product_id, sku

Optimization Tips:

→ Use grid tables for admin operations
→ Avoid loading full order with all items if not needed
→ Use getList() with SearchCriteria for filtering
→ Consider partitioning large order tables (enterprise installations)

Security & Authorization

Admin Access Control (ACL)

Resources defined in etc/acl.xml:

• Magento_Sales::sales - Main sales permission
• Magento_Sales::sales_order - Order management
• Magento_Sales::actions - Order actions (hold, cancel, etc.)
• Magento_Sales::sales_invoice - Invoice management
• Magento_Sales::sales_shipment - Shipment management
• Magento_Sales::sales_creditmemo - Credit memo management

Frontend Authorization

Customer Order View:

→ Plugin on order view controllers validates customer is logged in or has valid secret key
→ Guest orders require email + order ID + billing ZIP code