Track a parcel handled by multiple carriers

In case of a parcel handled by multiple carriers also called multi-leg delivery, create a delivery leg for each carrier with their respective tracking identifier.

Each delivery leg should share the same parcel reference that uniquely identifies the parcel. This parcel reference is used to collect information from delivery legs related to the parcel when querying the parcel journey using either of the tracking identifiers provided by the carriers.

In this example, a parcel with a unique parcel reference BOX-001 is delivered by two different carriers. Two delivery legs are created with their respective tracking identifiers and includes the parcel reference BOX-001. The carrier Fedex will handle the initial leg of the delivery and the carrier Colissimo will handle the final leg of the delivery.

Steps:

• Open the resource POST Create or update a delivery leg .
• Update the body with the following JSON object:

{
  "trackingIdentifier": "TRACK-MULTI-001",
  "carrierCode": "FEDEX",
  "parcel": {
    "parcelRef": "BOX-001"
  }
}

• Send the request to create the first delivery leg.
• Expect a successful response with 204 No Content response code.
• Update the body with the following JSON object:

{
  "trackingIdentifier": "TRACK-MULTI-002",
  "carrierCode": "COLISSIMO",
  "parcel": {
    "parcelRef": "BOX-001"
  },
  "finalDeliveryLeg": true
}

• Send the request to create the final delivery leg.
• Expect a successful response with 204 No Content response code.

After both delivery legs are created, then the parcel journey can be retrieved using either tracking identifiers used in the delivery legs.

• Open the resource GET Retrieve the parcel journeys for an order or a parcel .
• In the tab Parameters , set the value of the query parameter trackingIdentifier to either TRACK-MULTI-001 or TRACK-MULTI-002 .
• Remove all other query parameters so that only the query parameter trackingIdentifier is retained.
• Send the request to retrieve the parcel journey using the tracking identifier of the parcel.
• Expect a successful response with a 200 OK response code and the following JSON body:

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "parcel": {
            "parcelRef": "BOX-001",
            "deliveryLegs": [
                {
                    "carrierCode": "COLISSIMO",
                    "carrierTrackingURL": "https://www.coliposte.net/particulier/suivi_particulier.jsp?colispart=TRACK-MULTI-002",
                    "trackingIdentifier": "TRACK-MULTI-002",
                    "carrierDisplayName": "Colissimo",
                    "finalDeliveryLeg": true
                },
                {
                    "carrierCode": "FEDEX",
                    "carrierTrackingURL": "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=TRACK-MULTI-001",
                    "trackingIdentifier": "TRACK-MULTI-001",
                    "carrierDisplayName": "FedEx",
                    "finalDeliveryLeg": false
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

In this example, the parcel journey for the parcel reference BOX-001 has two delivery legs, one for each carrier delivering the parcel. The delivery leg for the carrier Colissimo is marked as final as this carrier will ensure the final mile delivery of the parcel. The other delivery leg for the carrier Fedex is marked as a non final so that delivery legs prior to the final one are clearly identified. Although the parcel has two delivery legs, all tracking events received for this parcel using either tracking identifiers will be unified under a single tracking history in the trackingEvents array sorted in chronological order.

The parcel journey is enriched with additional information respective to each delivery leg as previously described.

Summary: