Last indexed: 15 May 2026 (ea8ab8)

Sales and Order Management

This page provides a high-level overview of Maho's sales and order management infrastructure. It covers the overall architecture and relationships of the quote, order, and payment subsystems that facilitate the customer journey from shopping cart creation through order fulfillment and payment processing.

Detailed technical explanations on each subsystem are available in dedicated child pages:

Quote System — Lifecycle of quotes, quote item management, totals collection, and conversion to orders.
Order Processing — Order states, status management, invoicing, shipment creation, and order listing.
Payment System — Payment methods, PayPal Express Checkout integration, secure payment data handling, and webhook simulation.

System Overview

Maho’s sales management is divided into three core subsystems that represent successive stages along the purchase pipeline:

Subsystem	Main Models	Responsibility
Quote System	`Mage_Sales_Model_Quote`, `Mage_Sales_Model_Quote_Item`, `Mage_Sales_Model_Quote_Address`, `Mage_Sales_Model_Quote_Payment`	Manages the mutable shopping cart, addresses, applied rules, and payment intents before order placement.
Order System	`Mage_Sales_Model_Order`, `Mage_Sales_Model_Order_Item`, `Mage_Sales_Model_Order_Invoice`, `Mage_Sales_Model_Order_Shipment`	Maintains immutable transaction records representing finalized purchases and fulfillment states.
Payment System	`Mage_Sales_Model_Order_Payment`, `Mage_Payment_Model_Method_Abstract`, `Mage_Paypal_Model_Express_Checkout`	Handles payment gateway integrations, transaction processing, authorization, capture, and refunds.

System Relationships and Core Classes

This diagram shows the flow from a mutable quote through order conversion, including payment and fulfillment models.

Sources:
app/code/core/Mage/Sales/Model/Quote.php169-330
app/code/core/Mage/Sales/Model/Order.php13-167
app/code/core/Mage/Sales/Model/Order/Payment.php13-175
app/code/core/Mage/Adminhtml/controllers/Sales/Order/ShipmentController.php13-104

Quote System

The Quote subsystem models the user’s shopping cart, encapsulating product selections, quantities, and address/shipping selections prior to checkout completion. Its core entity Mage_Sales_Model_Quote holds quote items (Mage_Sales_Model_Quote_Item), which can represent complex product types such as Configurable, Bundle, or Grouped products.

Quote pricing considers product types’ specific price calculation logic, e.g., the configurable product price determines the final price by summing the base product price and selected options’ price impacts app/code/core/Mage/Catalog/Model/Product/Type/Configurable/Price.php13-195 The bundle product type handles SKU, weight, and price aggregation according to selected bundle options app/code/core/Mage/Bundle/Model/Product/Type.php13-171

For detailed description of quote lifecycle, item relationships, totals calculation, and conversion to orders, see Quote System.

Quote Entities and Product Type Interaction

Order Processing

After customer confirmation, the system converts the quote into an immutable Mage_Sales_Model_Order instance to record the completed transaction. The order system tracks order state (e.g., pending, processing, complete) and status, manages associated invoices and shipments, and provides administrative tools for order management.

Administrators can create shipments through the Mage_Sales_Model_Service_Order service model, which prepares shipment objects containing shipment items and optionally tracking information. The Mage_Adminhtml_Sales_Order_ShipmentController exposes shipment CRUD actions in the admin UI app/code/core/Mage/Adminhtml/controllers/Sales/Order/ShipmentController.php13-104

Order shipments and associated tracking numbers are maintained in Mage_Sales_Model_Order_Shipment and Mage_Sales_Model_Order_Shipment_Track respectively.

For a comprehensive walkthrough of order states, invoicing, shipment workflows, and backend grid management, see Order Processing.

Order Shipment Creation Workflow

Sources:
app/code/core/Mage/Adminhtml/controllers/Sales/Order/ShipmentController.php25-105
app/code/core/Mage/Sales/Model/Order.php13-167

Payment System

The payment subsystem handles the linkage of payment information to orders, supports multiple payment gateway methods, and implements standard payment operations such as authorization, capture, and void.

Each order has a related Mage_Sales_Model_Order_Payment instance that interacts with payment methods (Mage_Payment_Model_Method_Abstract) and specific gateway implementations like PayPal Express Checkout.

Localized strings for successful captures, pending transactions, and failed authorizations are maintained in translations for user feedback and administrative notices app/locale/en_US/Mage_Sales.csv104-125 Additionally, CLI commands exist for simulating PayPal webhook events to support development and testing of asynchronous payment notifications.

For detailed explanation of payment method setup, encryption, and webhook integration, see Payment System.

Payment Processing Relationships

Sources:
app/code/core/Mage/Sales/Model/Order/Payment.php13-175
app/locale/en_US/Mage_Sales.csv104-125

Integration with Other Systems

Product Types such as Downloadable app/code/core/Mage/Downloadable/Model/Product/Type.php13-15 and Virtual products influence order and shipment behavior by bypassing shipment creation.
The Payments subsystem integrates into the checkout flow, accessed by helpers like Mage_Checkout_Helper_Data to format prices and enforce checkout agreements app/code/core/Mage/Checkout/Helper/Data.php13-77
Newsletter subscriptions may be linked to the checkout process through Mage_Newsletter_Model_Subscriber, facilitating communication post-purchase app/code/core/Mage/Newsletter/Model/Subscriber.php43-87

This page provides the architectural context for sales-related models and services in Maho. For specifics on implementation, APIs, and customization points, please refer to the child pages:

Refresh this wiki

URL: https://deepwiki.com/MahoCommerce/maho/9-sales-and-order-management