Introducing a new hook for carrier modules to provide shipping detailed informations

[matks]

Context

For the module PrestaShop Checkout we would like to build a new feature called Shipping Tracking: the idea is to transfer the shipping detailed informations to the Payment provider who can use them to enhance the merchant experience and better follow the shipment status. It can be helpful for dealing with disputes.

As you know PrestaShop Checkout is built on top of PayPal, so we are referring to https://developer.paypal.com/docs/tracking/orders-api/integrate/

PrestaShop Core structure

PrestaShop native database structure does not handle multi-shipping orders or multi-carrier orders. It is designed for the situation where the whole order is sent as a single package using a single carrier.

Nowadays carriers who integrate PrestaShop have designed different solutions to handle multi-shipping orders (ship different parts of an order in multiple packages) and some also handle multi-carrier orders (ship different parts of an order in multiple packages, using different carriers). However there is no single way to do this in the Core sofware.

Introducing new hook

This is why we want to introduce a new hook

• to be triggered on ps_checkout side
• to be subscribed and handled on carrier modules side

This hook aims to gather the desired informations for ps_checkout to be able to send the shipping detailed informations to PayPal.

This hook will be introduced

• in ps_checkout next version
• as this is a generic need, relevant for all payment modules, it will also be introduced in PrestaShop next version to become available for everyone

How does it work

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 to hook will be used on ps_checkout side

$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
);

How the hook should be used on carrier module side

/**
 * 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)',
                ],
            ],
        ]
    ];
}

Expected return dormat: an array of shipment objects, even if there is only one shipment, or an empty array

• If you manage split shipments, return multiple entries with distinct tracking_number and associated products.
• Address, if the address for the delivery is different than the one the order (for example for pickup)
• Carrier name, if your module manages several carriers (Shipping platform)

How is the data is processed

Once received on ps_checkout side thanks to the hook, the data will be sent to PayPal (for ps_checkout, but it is relevant for another payment provider) to allow package tracking from the payment provider interface. The data transfer happens through API.

[matks]

The hook has been introduced in Checkout v5, see for example how it is handled for v8

ps_checkout/ps8/ps_checkout.php

Line 973 in 4ba4b7e

public function hookActionGetOrderShipments(array $params)