Track an order shipped using multiple parcels

While most orders are shipped using a single parcel, some larger orders are shipped using multiple parcels. In such scenario, it is important to retrieve at once all the parcel journeys of the parcels shipped for a given order.

In order to retrieve all parcel journeys for a given order, the information about the parcels provided by means of a delivery leg needs to include the order reference that uniquely identifies the order.

In this example, an order reference ORDER-01 is shipped by the carrier DHL express using two parcels referenced ORDER-01-PARCEL-01 and ORDER-01-PARCEL-02. Both parcels are tracked under their respective tracking identifiers TRACK-ORDER-01-PARCEL-01 and TRACK-ORDER-01-PARCEL-02

Steps:

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

{
  "trackingIdentifier": "TRACK-ORDER-01-PARCEL-01",
  "carrierCode": "DHL_EXP",
  "parcel": {
    "parcelRef": "ORDER-01-PARCEL-01"
  },
  "order": {
    "orderRef": "ORDER-01"
  }
}

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

{
  "trackingIdentifier": "TRACK-ORDER-01-PARCEL-02",
  "carrierCode": "DHL_EXP",
  "parcel": {
    "parcelRef": "ORDER-01-PARCEL-02"
  },
  "order": {
    "orderRef": "ORDER-01"
  }
}

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

Retrieve all the parcel journeys for a given order reference

After the delivery legs have been created, parcel journeys for all the parcels shipped as part of an order are available using the order reference as query parameter.

• 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 orderRef to ORDER-01 .
• Remove all other query parameters so that only the query parameter orderRef is retained.
• Send the request to retrieve all the parcel journeys of an order using the order reference.
• Expect a successful response with a 200 OK response code and the following JSON body:

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-01"
        },
        "parcel": {
            "parcelRef": "ORDER-01-PARCEL-01",
            "deliveryLegs": [
                {
                    "carrierCode": "DHL_EXP",
                    "trackingIdentifier": "TRACK-ORDER-01-PARCEL-01",
                    "carrierDisplayName": "DHL Express",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    },
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-01"
        },
        "parcel": {
            "parcelRef": "ORDER-01-PARCEL-02",
            "deliveryLegs": [
                {
                    "carrierCode": "DHL_EXP",
                    "trackingIdentifier": "TRACK-ORDER-01-PARCEL-02",
                    "carrierDisplayName": "DHL Express",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

The response includes the two parcel journeys for the parcels that are used to ship the order. Each parcel includes order information with the reference of the order. As parcels have specific tracking identifiers, they are tracked independently with their respective tracking history.

New information included in the parcel journey:

• order : block of information related to the order.
  • orderRef : the reference that uniquely identify the order and the parcels used to ship the order.

Retrieve a specific parcel journey for a given tracking identifier

The parcel journey for a single parcel remains available using the tracking identifier of the parcel. When retrieving a parcel journey using the tracking identifier access pattern, only the information for this parcel will be returned, even if the parcel is part of a bigger shipment for an order.

• 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 TRACK-ORDER-01-PARCEL-01 .
• Remove all other query parameters so that only the query parameter trackingIdentifier is retained.
• Send the request to retrieve only the parcel journey for the parcel tracked under the given tracking identifier.
• Expect a successful response with a 200 OK response code and the following JSON body:

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-01"
        },
        "parcel": {
            "parcelRef": "ORDER-01-PARCEL-01",
            "deliveryLegs": [
                {
                    "carrierCode": "DHL_EXP",
                    "trackingIdentifier": "TRACK-ORDER-01-PARCEL-01",
                    "carrierDisplayName": "DHL Express",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

The response only includes information about the specific parcel tracked under TRACK-ORDER-01-PARCEL-01. It no longer includes information about other parcels shipped as part of the same order.

Summary: