Connecting Fulfillment Providers to Magento 2: A Practical Guide

1. What a fulfillment provider takes over for Magento

A fulfillment provider such as DHL Fulfillment, Rhenus or a specialized 3PL company takes over warehousing, picking, packaging and shipping physical orders placed in the Magento shop. For the shop operator this eliminates in house warehouse logistics, but it also creates a new technical dependency: Magento must transfer orders to the fulfillment provider and reliably process its feedback on shipping and stock. A good fulfillment integration makes this external provider ideally invisible to the customer.

The challenge is that a fulfillment provider typically runs its own warehouse management system with its own data model, which rarely matches Magento's order model one to one. Partial shipments, multiple warehouse locations or special rules for hazardous goods require a fulfillment integration that goes beyond a simple order export and covers the entire order lifecycle from transfer to delivery confirmation.

2. Integration architecture: export, import, stock

A resilient fulfillment integration consists of three independent data flows, each with its own latency requirements. Order export from Magento to the fulfillment provider must happen quickly so orders get picked promptly. Stock import from the fulfillment provider back to Magento must also be timely, so the shop does not offer items no longer available in the warehouse. Shipment status import, by contrast, can run with a bit more delay without customers noticing.

These three data flows should be implemented as technically separate, usually through dedicated consumers within Magento's message queue framework. A fulfillment integration that bundles all three flows into a single synchronous script will, on a provider outage, block all three functions simultaneously instead of only pausing the affected sub process.

<!-- app/code/Mironsoft/FulfillmentIntegration/etc/queue_topology.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:MessageQueue/etc/topology.xsd">
    <exchange name="fulfillment" type="topic" connection="amqp">
        <binding id="orderExportBinding" topic="fulfillment.order.export" destinationType="queue" destination="fulfillment_order_export"/>
        <binding id="stockImportBinding" topic="fulfillment.stock.import" destinationType="queue" destination="fulfillment_stock_import"/>
        <binding id="shipmentImportBinding" topic="fulfillment.shipment.import" destinationType="queue" destination="fulfillment_shipment_import"/>
    </exchange>
</config>

3. Order export to the fulfillment provider

Once an order is completed and paid at checkout, the fulfillment integration must transfer it in a structured way to the provider: items with SKU and quantity, delivery address, chosen shipping method and any special instructions such as gift wrapping. The export should be triggered by the observer for the sales_order_invoice_pay event or a comparable event, not already on plain order creation, so unpaid or canceled orders are not accidentally picked.

A common mistake in fulfillment integration is running the export synchronously within the checkout process. That couples the customer's response time to the fulfillment provider's availability. The export should instead run asynchronously via a message queue, with a confirmation from the provider that the order was accepted before Magento marks it as successfully transferred to the fulfillment provider.

<?php

declare(strict_types=1);

namespace Mironsoft\FulfillmentIntegration\Model\Queue;

use Magento\Sales\Api\Data\OrderInterface;
use Psr\Log\LoggerInterface;

/**
 * Builds and sends the fulfillment order export payload to the 3PL provider.
 */
final class OrderExportProcessor
{
    public function __construct(
        private readonly FulfillmentApiClient $apiClient,
        private readonly LoggerInterface $logger
    ) {
    }

    /**
     * Transforms and transmits an order to the fulfillment provider.
     *
     * @param OrderInterface $order Paid Magento order ready for fulfillment
     * @return void
     */
    public function export(OrderInterface $order): void
    {
        $payload = [
            'order_reference' => $order->getIncrementId(),
            'shipping_address' => $this->mapAddress($order->getShippingAddress()),
            'items' => $this->mapItems($order->getAllVisibleItems()),
            'shipping_method' => $order->getShippingMethod(),
        ];

        $response = $this->apiClient->createOrder($payload);

        if (!$response->isAccepted()) {
            $this->logger->error('Fulfillment provider rejected order', ['order' => $order->getIncrementId()]);
            throw new \RuntimeException('Fulfillment export rejected: ' . $response->getReason());
        }
    }

    /**
     * Maps a Magento shipping address to the provider address format.
     *
     * @param \Magento\Sales\Api\Data\OrderAddressInterface $address Order shipping address
     * @return array Address payload for the fulfillment API
     */
    private function mapAddress($address): array
    {
        return [
            'name' => $address->getFirstname() . ' ' . $address->getLastname(),
            'street' => implode(' ', $address->getStreet()),
            'city' => $address->getCity(),
            'postal_code' => $address->getPostcode(),
            'country' => $address->getCountryId(),
        ];
    }

    /**
     * Maps Magento order items to the provider item format.
     *
     * @param array $items Visible order items
     * @return array List of item payloads with SKU and quantity
     */
    private function mapItems(array $items): array
    {
        return array_map(static fn ($item) => [
            'sku' => $item->getSku(),
            'quantity' => (int) $item->getQtyOrdered(),
        ], $items);
    }
}

4. Stock and MSI synchronization

Because physical stock sits with the fulfillment provider, Magento must regularly receive current stock data from the provider through Multi Source Inventory. The fulfillment integration models this in MSI as a dedicated source for the external warehouse, whose stock quantity is updated exclusively through the stock import, never manually in the Magento admin panel. That way it stays unambiguous which system is responsible for which value.

The frequency of this synchronization is critical: a daily stock reconciliation is often insufficient for fast moving items and leads to oversells that have to be canceled afterward. Most production fulfillment integrations therefore use event based stock reconciliation, where the provider reports every relevant stock change immediately via a webhook, supplemented by an hourly full reconciliation as a safety net against lost individual events.

5. Processing shipment status and tracking updates

Once the fulfillment provider has packed an order and handed it to a carrier, the fulfillment integration must transfer that status, including the tracking number, back to Magento so the customer sees the current shipment status in their account and the corresponding shipment confirmation email is triggered. Technically this means creating a Magento shipment record for the affected order with the tracking number of the respective carrier.

For partial shipments, when one item from an order ships separately, the fulfillment integration must correctly represent multiple shipment records per order, each with its associated line items and its own tracking number. A common implementation mistake is allowing only a single shipment per order, which leads to wrong or incomplete tracking information in the customer account when partial shipments occur.

{
  "event": "shipment.dispatched",
  "order_reference": "100003421",
  "shipment_id": "ffl-8821-1",
  "carrier": "dhl",
  "tracking_number": "00340434123456789012",
  "items": [
    { "sku": "SHIRT-BLUE-M", "quantity": 2 }
  ]
}

6. Returns workflow with the fulfillment partner

Returns are often the least thought through part of a fulfillment integration, because unlike the order process they follow no linear flow. A customer initiates a return in the Magento account or by email, but the physical package goes directly to the fulfillment provider's warehouse, not to Magento. The fulfillment integration must therefore be able to process feedback from the provider once the returned goods have arrived and been inspected in the warehouse.

This feedback typically triggers the creation of a credit memo in Magento and, depending on the condition of the goods, a stock correction in the corresponding MSI source. Importantly, the fulfillment integration must distinguish between resellable and damaged goods, because only the former may increase available stock. Without this distinction, the shop resells items that are actually no longer sellable.

7. Error scenarios: partial shipments and discrepancies

In practice, every fulfillment integration encounters discrepancies: an item is actually unavailable in the warehouse even though stock signaled otherwise, an address is undeliverable, or the provider can only ship part of the order. Each of these scenarios needs a defined feedback channel in the integration: for an unavailable item, the system automatically cancels the affected line and informs the customer, instead of leaving the entire order in indefinite limbo.

For partial shipments, the fulfillment integration must distinguish between a planned partial shipment, for example because an item is being replenished from a different warehouse, and an unplanned partial shipment due to an actual stock discrepancy. Only in the latter case should an automatic notification go to category management, so stock data in the PIM or ERP is corrected before the error repeats.

8. SLA monitoring and escalation processes

Fulfillment providers usually operate under contractually agreed service level agreements, such as a maximum time between order receipt and shipment. A good fulfillment integration measures this time automatically for every order and reports breaches, instead of relying on manual spot checks. A dashboard showing the average and maximum processing time over the last 24 hours reveals systematic problems at the provider before customers complain.

For critical deviations, for example when an order has been in the system for more than 48 hours without a shipment confirmation, the fulfillment integration should automatically trigger an escalation to the responsible contact at the provider, instead of waiting for a shop employee to manually discover the backlog. This automation significantly reduces response time for real operational problems.

9. Integration models compared

Several models are available for the technical connection of a fulfillment provider, differing significantly in latency and implementation effort.

For most Magento shops with a single fulfillment provider, a REST API coupling with event based webhook additions for time critical events such as stock shortages is the best trade off between implementation effort and freshness. Those orchestrating multiple providers simultaneously, for example across different countries, benefit from a dedicated fulfillment middleware that unifies the fulfillment integration across all providers.

10. Summary

A resilient fulfillment integration in Magento 2 separates order export, stock reconciliation and shipment status import into three independent, asynchronous data flows, each with its own latency requirements. MSI models the fulfillment provider's stock as a dedicated source, shipment records with correct tracking numbers make partial shipments traceable for the customer, and a well designed returns workflow distinguishes resellable from damaged goods.

Error scenarios such as undeliverable addresses or actual stock discrepancies need defined, automated feedback channels instead of manual rework. SLA monitoring with automatic escalation ensures that delays at the fulfillment provider surface before they turn into customer complaints. Together, these building blocks turn a fulfillment integration into a robust, largely invisible part of order processing.

11. FAQ: Connecting Fulfillment Providers to Magento 2