Shipping & Carrier Management
Relevant source files
The following files were used as context for generating this wiki page:
Shipping & Carrier Management handles the logistics of product delivery, carrier configuration, and shipment processing. It enables merchants to define delivery methods, calculate shipping fees based on weight or price ranges, and manage multi-carrier scenarios where different products in a single order require separate logistics.
The system integrates frontend checkout processes with backend administrative controls, allowing for precise tracking of packages and automated selection of carriers based on customer location and product attributes.
Carrier Configuration and Properties
Carriers represent the entities responsible for transporting goods. Each carrier contains specific metadata including name, transit time, and speed grades. Merchants configure these properties to inform customers about delivery expectations during the checkout process.
Core Carrier Attributes
The Carrier class defines the structural data for delivery services.
| Field | Type | Description |
|---|---|---|
name | string | The public name of the carrier service. |
active | bool | Indicates if the carrier is available for selection. |
is_free | bool | Determines if shipping is free regardless of other rules. |
shipping_handling | bool | Applies handling costs if enabled. |
range_behavior | bool | Defines behavior when a value is outside defined ranges. |
shipping_external | bool | Marks the carrier as an external module service. |
need_range | bool | Indicates if the carrier requires weight/price ranges. |
Sources: classes/Carrier.php:48-115
Global Carrier Options
The CarrierOptionsConfiguration class manages system-wide shipping settings that affect all active carriers.
- Default Carrier: Sets the primary carrier selected for new orders.
- Carrier Sort Order: Determines how carriers appear to the customer (e.g., by price or position).
- Sort Way: Sets ascending or descending order for the display list.
Sources: src/Core/Domain/Carrier/CarrierOptionsConfiguration.php:48-55
Shipment Logic and Multi-Carrier Handling
The system supports complex shipping scenarios where multiple carriers fulfill a single order. This occurs when products have specific carrier restrictions or when virtual products (requiring no delivery) are mixed with physical goods.
Shipment Merging
The ShipmentMerger component consolidates individual product shipments into logical delivery groups. It iterates through order items and groups them by their assigned delivery options.
The diagram shows how order items are partitioned into shipments based on product type and carrier assignment.
Sources: src/Core/Domain/Shipment/ShipmentMerger.php:38-65
Multi-Carrier Checkout Flow
When an order contains products restricted to different carriers, the checkout process displays a combined shipping summary.
- Carrier Selection: The customer views available carriers. If products require different carriers, the system displays a concatenated list of names (e.g., "Carrier A, Carrier B").
- Product Association: The payment and summary steps explicitly show which product is delivered by which carrier.
- Virtual Products: Products marked as virtual are identified in the checkout with a "no delivery service" notice.
Sources: tests/UI/campaigns/functional/FO/classic/12_orderConfirmation/06_multicarrier.ts:400-450
Fee Calculation and Range Management
Shipping costs are calculated based on weight or price ranges defined for each carrier.
- Handling Fees: Fixed costs for packing and processing, which are applied if
shipping_handlingis enabled. - Transport Fees: Variable costs that change according to the total weight of the shipment.
- Range Validation: If an order's weight or price exceeds the maximum defined range, the system follows the
range_behavior(either applying the highest cost or disabling the carrier).
Sources: classes/Carrier.php:80-90, install-dev/langs/en/data/cms.xml:6-10
Tracking and Delivery Fulfillment
Tracking information allows customers to monitor their package status. Merchants provide a tracking URL template per carrier, which the system populates with the specific tracking number once the order is shipped.
Fulfillment Process
- Identify Shipment: Select the specific shipment group within an order in the Back Office.
- Assign Tracking: Input the tracking number provided by the logistics partner.
- Customer Notification: The tracking number becomes visible in the Front Office Order History and Details page.
Sources: tests/UI/campaigns/functional/FO/classic/12_orderConfirmation/06_multicarrier.ts:510-530, classes/Carrier.php:120
Order Details View
The customer's order details table provides transparency for multi-shipment orders.
| Column | Description |
|---|---|
| Carrier | The name of the specific carrier for that package. |
| Weight | The total weight of the products in that shipment. |
| Shipping Cost | The calculated cost for that specific delivery. |
| Tracking Number | The reference code for external tracking. |
Sources: tests/UI/campaigns/functional/FO/classic/12_orderConfirmation/06_multicarrier.ts:480-495
Summary
Shipping & Carrier Management ensures that logistics rules are accurately applied from configuration to delivery. By utilizing specific classes for range behavior and shipment merging, the system handles both simple single-carrier deliveries and complex multi-carrier orders, providing clear tracking and cost breakdowns for both merchants and customers.