Module Integrations - Magento_Sales Documentation

Integration Overview

The Sales module is a core business module that orchestrates order management, invoicing, shipping, and refunds. It acts as a central hub connecting customer data, catalog products, payment processing, and fulfillment.

Integration Categories

→ Direct Dependencies - Modules Sales depends on
→ Dependent Modules - Modules that depend on Sales
→ Cross-Module Plugins - Sales intercepts other modules
→ Event-Based Integration - Loose coupling via events
→ External Integrations - Third-party systems and APIs

Direct Dependencies

These modules are required by Sales (defined in module.xml). The Sales module cannot function without these core dependencies.

Magento_Customer

Customer Data Association

Orders associate with customers (registered or guest). Customer data is denormalized into the order table to improve performance and preserve historical data.

Integration Type

Database foreign keys, observers, service contracts

Key Fields

customer_id, customer_email, customer_group_id, customer_is_guest

Magento_Quote

Quote to Order Conversion

Critical Dependency - Orders are created from quotes (shopping carts). The conversion process handles payment, inventory deduction, and order finalization.

Service

QuoteManagement::submit()

Process

Validate → Reserve ID → Convert → Save → Deduct Inventory → Email

Magento_Catalog

Product Data Reference

Order items reference catalog products. Product type handlers manage configurable, bundle, and simple products with different order item creation strategies.

Integration Type

Database foreign keys, product type handlers

Key Fields

product_id, product_type, name, sku, weight

Magento_Store

Multi-Store Context

Orders are scoped to store views for multi-store support. Handles currency conversion, locale settings, and store-specific email templates.

Integration Type

Store context, currency, locale

Key Fields

store_id, store_name, store_currency_code, base_currency_code

Dependent Modules

These modules depend on Sales and extend its functionality. They provide critical business capabilities like payment processing, shipping, and tax calculation.

Magento_Payment

Payment Processing

Orders require payment processing. Handles authorization, capture, and refund workflows for various payment methods.

Flow

Authorize → Capture (on invoice) → Refund (on credit memo)

Magento_Shipping

Shipping Methods & Tracking

Orders require shipping method selection and tracking. Integrates with carriers for rate calculation and label generation.

Carriers

UPS, FedEx, USPS, DHL

Magento_Tax

Tax Calculation

Orders must calculate taxes based on customer location and product tax class. Supports complex multi-jurisdictional tax rules.

Process

Customer class + Product class + Location → Tax rate

Magento_Inventory (MSI)

Multi-Source Inventory

Magento 2.3+ - Advanced inventory management with multiple warehouses. Uses source selection algorithms and inventory reservations.

Strategy

Reservation on order → Deduction on shipment

Event-Based Integration

Sales module dispatches events that other modules observe for loose coupling. This enables extensibility without direct dependencies.

Critical Events

sales_order_place_after

Order Placement Complete

Dispatched after order is successfully placed. Multiple modules react to trigger inventory deduction, coupon tracking, and order processing.

Key Observers

• SubtractQuoteInventoryObserver - Deduct inventory
• PlaceReservationsForSalesEventObserver - MSI reservations
• AssignCouponDataAfterOrderCustomerAssignObserver - Coupon tracking

sales_order_invoice_pay

Invoice Payment Captured

Dispatched after invoice is paid (payment captured). Triggers fulfillment actions like activating downloadable products or gift cards.

Key Observers

• GridSyncInsertObserver - Update invoice grid
• SetLinkStatusInvoicedObserver - Activate downloadable links
• ToggleGiftCardObserver - Activate gift cards

sales_order_shipment_save_after

Shipment Created

Dispatched after shipment is saved. Triggers inventory deduction from specific sources and sends tracking emails to customers.

Key Observers

• SourceDeductionProcessor - Deduct MSI inventory
• TrackingNumberObserver - Send tracking email
• GridSyncInsertObserver - Update shipment grid

sales_order_creditmemo_refund

Refund Processed

Dispatched after credit memo is refunded. Triggers inventory return, MSI reservation compensation, and coupon usage restoration.

Key Observers

• RefundOrderInventoryObserver - Return inventory
• RefundOrderInventoryObserver (MSI) - Compensate reservations
• RestoreCouponUsageObserver - Restore coupon count

External Integrations

Sales module provides integration points for third-party systems. These integrations enable payment processing, shipping, ERP connectivity, and tax services.

Payment Gateways

Third-Party Payment Processing

Integration pattern using payment method adapters implementing MethodInterface. Supports authorize, capture, and refund workflows.

• Stripe - Modern payment processing

• PayPal - Express checkout integration

• Braintree - PayPal-owned gateway

• Authorize.Net - Legacy gateway support

Shipping Carriers

Carrier API Integration

Integration pattern using carrier adapters implementing CarrierInterface. Provides rate calculation and label generation.

• UPS - United Parcel Service

• FedEx - Federal Express

• USPS - United States Postal Service

• DHL - International shipping

ERP Systems

Enterprise Resource Planning

Order export via REST API or message queue. Enables bi-directional synchronization between Magento and enterprise systems.

• SAP - Enterprise resource planning

• Oracle - Business management suite

• NetSuite - Cloud ERP platform

• Microsoft Dynamics - Business applications

Tax Services

Real-Time Tax Calculation

Real-time tax calculation via API. Provides accurate sales tax rates for complex multi-jurisdictional scenarios.

• Avalara - Automated tax compliance

• TaxJar - Sales tax calculation & filing

• Vertex - Enterprise tax solutions

• Sovos - Global tax automation

Integration Best Practices

Service Contracts for Loose Coupling

Good: Use repository pattern with service contracts

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

Why: Service contracts provide API stability and allow plugin interception.

Use Events for Cross-Module Communication

Good: Dispatch event, let observer handle it

$this->eventManager->dispatch('sales_order_place_after', ['order' => $order]);

Why: Other modules can react to events without Sales module knowing about them.

Use Message Queues for External Integrations

Good: Publish message to queue for async processing

$this->publisher->publish('erp.order.export', $order->getId());

Why: External APIs can fail or be slow. Don't block critical order flow.

Preserve Historical Data (Denormalization)

Why: Product name/price/SKU can change after order is placed. Copy product data to order at time of placement:

$orderItem->setName($product->getName());
$orderItem->setPrice($product->getFinalPrice());

Result: Order displays product as it was when purchased, not current version.

Quote to Order Data Flow

Understanding the conversion process from shopping cart (Quote) to finalized order (Order).

Quote Field	Order Field	Notes
`quote.entity_id`	`order.quote_id`	Reference to source quote
`quote.grand_total`	`order.grand_total`	Final amount
`quote.customer_id`	`order.customer_id`	NULL for guest orders
`quote.customer_email`	`order.customer_email`	Required field
`quote.billing_address_id`	`order.billing_address`	Converted to OrderAddressInterface
`quote.shipping_address_id`	`order.shipping_address`	Converted to OrderAddressInterface
`quote.items`	`order.items`	Converted to OrderItemInterface[]