Reallocate a parcel to a new tracking identifier

In case the tracking identifier of a parcel changes, create a new leg for the parcel containing the newly allocated tracking identifier by means of a delivery leg.

After reallocation, the original tracking identifier becomes obsolete and no tracking events will be received for that identifier. You can decide to delete the obsolete delivery leg by using its tracking identifier. Once deleted, the obsolete delivery leg will no longer be returned in the parcel journey.

In this example the tracking identifier of the parcel tracked under TRACK-REALLOC-OBSOLETE changes to TRACK-REALLOC-NEW. Two delivery legs will be created with their respective tracking identifiers and a unique parcel reference PARCEL-REALLOC will be used to link the two delivery legs to the same parcel.

Steps:

Open the resource POST Create or update a delivery leg .
Update the body with the following JSON object which contains the original tracking identifier:

Copy

Copied

{
  "trackingIdentifier": "TRACK-REALLOC-OBSOLETE",
  "parcel": {
    "parcelRef": "PARCEL-REALLOC"
  }
}

Send the request.
Expect a successful response with 204 No Content response code.
Update the body with the following JSON object which contains the new tracking identifier:

Copy

Copied

{
  "trackingIdentifier": "TRACK-REALLOC-NEW",
  "parcel": {
    "parcelRef": "PARCEL-REALLOC"
  }
}

Send the request.
Expect a successful response with 204 No Content response code.

After the delivery legs are created 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 the original TRACK-REALLOC-OBSOLETE or TRACK-REALLOC-NEW .
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:

Copy

Copied

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "parcel": {
            "parcelRef": "PARCEL-REALLOC",
            "deliveryLegs": [
                {
                    "trackingIdentifier": "TRACK-REALLOC-NEW",
                    "finalDeliveryLeg": true
                },
                {
                    "trackingIdentifier": "TRACK-REALLOC-OBSOLETE",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

You can decide to remove the delivery leg with the obsolete tracking identifier TRACK-REALLOC-OBSOLETE as it contains obsolete information and no tracking events will be received for this identifier.

Open the resource Delete delivery legs for a given tracking identifier .
In the tab Parameters , set the value of the query parameter trackingIdentifier to TRACK-REALLOC-OBSOLETE .
Send the request.
Expect a successful response with a 200 OK response code and the following JSON body:

Copy

Copied

{
  "message": "Deleted 1 delivery legs"
}

After deleting the obsolete delivery leg, the parcel journey only contains information from the delivery leg associated with the new tracking identifier.

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 the original TRACK-REALLOC-OBSOLETE or TRACK-REALLOC-NEW .
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:

Copy

Copied

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "parcel": {
            "parcelRef": "PARCEL-REALLOC",
            "deliveryLegs": [
                {
                    "trackingIdentifier": "TRACK-REALLOC-NEW",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

Note: The Tracking API will continue to support retrieving parcel journeys using tracking identifiers for which delivery legs were deleted. This ensures that parcel journeys remain accessible when using obsolete tracking identifiers that could have been communicated to shoppers by means of notifications (email, SMS) at an early stage of the processing of the parcels.