With the Shipping Tracking feature, our goal is to collect all information related to a shipment such as tracking number, packing list, delivery address and provide these information automatically to Payment modules, starting with PrestaShop Checkout.

If you are building a delivery module for PrestaShop, we need your help in order to make everything automatic.

Our end goal is to innovate and improve the quality of the information being transferred between Delivery (carrier) modules and Payment modules.

How

We are going to rely on PrestaShop hook system for the data transfer. A new hook actionGetOrderShipments will be introduced:

• in PrestaShop Checkout module, starting from version 5.0.0
• in PrestaShop v9.0.0 We hope other Payment modules will also seize the opportunity to set a new standard

[!IMPORTANT]
The hook will start to used on PrestaShop Checkout 5.0.0 which is compatible with PrestaShop 1.7, 8 and 9. This means this hook should be implemented in Carrier modules for all three versions PrestaShop 1.7, 8 and 9

This hook will be used by Payment modules to pull delivery details from carrier modules.

/**
 * If your module manages shipment and shipping labels,
 * You can use this hook to share shipment data with third party modules.
 *
 * @param array{id_order: int, id_carrier: int} $params
 *
 * @return array
 */
public function hookActionGetOrderShipments(array $params): array
{
    // Returns an empty array if your module has nothing to send
    if (empty($params['id_order'])) {
        return [];
    }
        
    // Returns an array of shipments if you have data to share
    // Based on data you sent to create a shipping label
    return [
        [
            'carrier' => 'Standard carrier name',
            'tracking_number' => '123456789',
            'status' => 'SHIPPED',
            'address' => [
                'address_line_1' => '2211 N First Street',
                'address_line_2' => 'Building 17',
                'admin_area_2' => 'San Jose',
                'admin_area_1' => 'CA',
                'postal_code' => '95131',
                'country_code' => 'US',
            ],
            'products' => [
                [
                    'id_product' => 1,
                    'id_product_attribute' => 1,
                    'reference' => 'demo_1',
                    'quantity' => 1,
                    'name' => 'Hummingbird printed t-shirt (Size: S - Color: White)',
                ],
            ],
        ]
    ];
}

Data structure in details

Hook	actionGetOrderShipments
Locations	Backoffice
Type	action
Origin	module
Description	This hook is called by third party carrier modules that need to retrieve the shipments information for an order.
Expected Return	array of shipments or empty array

The expected data format is

[
    'carrier name',
    'tracking_number',
    'status',
    'address' => [
        'address_line_1',
        'address_line_2',
        'admin_area_2',
        'admin_area_1',
        'postal_code',
        'country_code',
    ],
    'products' => [
        [
            'id_product',
            'id_product_attribute',
            'reference',
            'quantity',
            'name',
        ],
    ],
]

Example:

[
   'carrier' => 'Standard carrier name',
   'tracking_number' => '123456789',
   'status' => 'SHIPPED',
   'address' => [
       'address_line_1' => '2211 N First Street',
       'address_line_2' => 'Building 17',
       'admin_area_2' => 'San Jose',
       'admin_area_1' => 'CA',
       'postal_code' => '95131',
       'country_code' => 'US',
   ],
   'products' => [
       [
           'id_product' => 1,
           'id_product_attribute' => 1,
           'reference' => 'demo_1',
           'quantity' => 1,
           'name' => 'Hummingbird printed t-shirt (Size: S - Color: White)',
       ],
   ],
]

How the hook will be used from a Payment module

$order = new Order((int) Tools::getValue('id_order'));
$carrier = new Carrier((int) $order->id_carrier);
$carrierModuleId = null;
if ($carrier->external_module_name) {
    $carrierModule = Module::getInstanceByName($carrier->external_module_name);
    if ($carrierModule) {
        $carrierModuleId = $carrierModule->id ?? null;
    }
}
$carrierModule = Module::getInstanceByName($order->id_carrier);
$orderShipments = Hook::exec(
    'actionGetOrderShipments',
    [
        'id_order' => (int) $order->id,
        'id_carrier' => (int) $order->id_carrier,
    ],
    $carrierModuleId
);

This hook allows a Carrier Module to share shipment-level data (tracking, address, product list) with third-party modules like PrestaShop Checkout. These modules can then enrich the order tracking information sent to PayPal or fraud detection services, particularly when orders are split into multiple shipments.

This hook is called by third-party modules when:

• Retrieving order tracking information for synchronization with third party service
• Collecting shipment data to enhance delivery and dispute protection services
• Multiple shipments or non-standard delivery address logic is expected

What are the benefits for merchants?

Thanks to this hook, the Payment provider will be able to solve part of the disputes between the buyer and the merchant automatically. Each year, several disputes are created between merchant’s and buyer. Consequences ? Merchants spend so much time solving manually these disputes and might loose money if they don’t have enough delivery proof.

Severals benefits are expected for merchants from this feature :

✅ Merchants will save some money as disputes will be automatically solved

✅ Merchants will reduced the time spent on solving delivery disputes

✅ Reduce by 20% the number of disputes solved in the favor of the client vs the merchant

✅ Facilitate the delivery disputes process

✅ Reduce by 30% the number of delivery disputes

What are the benefits for you, carrier modules?

✅ Reduction of disputes and information requests

✅ Reduction of support workload

✅ Strengthening collaboration with PayPal and merchants

Questions?

Don't hesitate to ask questions and submit suggestions in the Discussion we created for that.