Cancel the delivery for an order or a parcel

When an order is no longer being shipped, the delivery for this order can be cancelled before despatch by means of a delivery event with the event code CANCELLED_BEFORE_DESPATCH.

When a parcel is no longer being shipped, the delivery leg for this parcel can be cancelled before despatch by means of a delivery leg event with the event code CANCELLED_BEFORE_DESPATCH.

After cancelling the delivery for an order or a parcel, the parcel journeys for this order or parcel is no longer returned when using Retrieve parcel journeys in the API.

Cancelling the delivery for an order or a parcel does not delete information. Instead, the parcel journeys that relate to the cancellation are excluded from the response returned by the API.

The Tracking API supports the following cancellation types:

Cancelling an order entirely, which involves sending a cancellation event for each delivery created for the specified order.
Cancelling a specific delivery for an order, which involves sending a cancellation event for the specific delivery that is cancelled.
Cancelling a specific parcel, which involves sending a cancellation event using a tracking identifier used to track the parcel. All delivery legs for this parcel will be cancelled automatically and the parcel journey will no longer be available, so there is no need to send a cancellation event for each delivery leg that could have been created for the parcel.

Note: When cancelling an order or a delivery, all associated delivery legs that would have been created for the given delivery reference will be cancelled automatically, so there is no need to send additional cancellation events for the delivery legs using the same tracking identifier.

Cancel an order entirely

The cancellation of an order is achieved by sending a delivery event with the event code CANCELLED_BEFORE_DESPATCH for each delivery that have been created for the order.

In this example, an order with a unique reference ORDER-CANCELLED is cancelled by the customer who no longer wants the items. This order was initially planned to ship the items from two distinct warehouses and as such two deliveries have been created with their respective unique delivery reference DELIVERY-CANCELLED-WAREHOUSE-1 and DELIVERY-CANCELLED-WAREHOUSE-2.

As initially planned two delivery legs have been created for the two parcels in the order with their respective tracking identifiers PARCEL-CANCELLED-1 and PARCEL-CANCELLED-2

Two delivery event CANCELLED_BEFORE_DESPATCH are published to cancel both deliveries using their unique delivery references.

Steps:

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

Copy

Copied

{
  "order": {
    "orderRef": "ORDER-CANCELLED"
  },
  "deliveryRef": "DELIVERY-CANCELLED-WAREHOUSE-1"
}

Send the request to create the first delivery with the order information.
Expect a successful response with 204 No Content response code.
Update the body with the following JSON object that defines the second delivery of the order:

Copy

Copied

{
  "order": {
    "orderRef": "ORDER-CANCELLED"
  },
  "deliveryRef": "DELIVERY-CANCELLED-WAREHOUSE-2"
}

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

Copy

Copied

{
  "trackingIdentifier": "PARCEL-CANCELLED-1",
  "deliveryRef": "DELIVERY-CANCELLED-WAREHOUSE-1"
}

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:

Copy

Copied

{
  "trackingIdentifier": "PARCEL-CANCELLED-2",
  "deliveryRef": "DELIVERY-CANCELLED-WAREHOUSE-2"
}

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

Let's take a look at the initial state for this order before cancellation.

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

Copy

Copied

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-CANCELLED"
        },
        "parcel": {
            "deliveryRef": "DELIVERY-CANCELLED-WAREHOUSE-2",
            "deliveryLegs": [
                {
                    "trackingIdentifier": "PARCEL-CANCELLED-2",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    },
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-CANCELLED"
        },
        "parcel": {
            "deliveryRef": "DELIVERY-CANCELLED-WAREHOUSE-1",
            "deliveryLegs": [
                {
                    "trackingIdentifier": "PARCEL-CANCELLED-1",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

Two distinct parcel journeys are returned for this order where each parcel journey includes information from its respective delivery and delivery leg. This is expected as initially the order is planned to be delivered in two separate deliveries despatched from two distinct warehouses.

The customer cancels the order as the items are no longer wanted. The two deliveries planned for this order require cancellation. A delivery event CANCELLED_BEFORE_DESPATCH is sent for each delivery using its respective unique delivery reference.

Open the resource POST Add events for a delivery
Update the body with the following JSON object that defines the first delivery event:

Copy

Copied

{
  "deliveryRef": "DELIVERY-CANCELLED-WAREHOUSE-1",
  "eventCode": "CANCELLED_BEFORE_DESPATCH",
  "eventDate": "2022-07-18T16:20:42.306Z",
  "eventTimeZone": "Europe/London"
}

Send the request to publish the delivery event that cancels the first delivery.
Expect a successful response with 204 No Content response code.
Update the body with the following JSON object that defines the second delivery event:

Copy

Copied

{
  "deliveryRef": "DELIVERY-CANCELLED-WAREHOUSE-2",
  "eventCode": "CANCELLED_BEFORE_DESPATCH",
  "eventDate": "2022-07-18T16:20:42.403Z",
  "eventTimeZone": "Europe/London"
}

Send the request to publish the delivery event that cancels the second delivery.
Expect a successful response with 204 No Content response code.

Let's try to retrieve the parcel journeys for this order now that the order has been cancelled.

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

Copy

Copied

[]

No parcel journeys are returned as the order has been entirely cancelled.

Note: Cancelling a delivery also takes care of cancelling its associated delivery legs.

Summary:

Number of deliveries	Number of delivery legs	Number of cancellation events	Number of Parcel Journeys
1	Any	0	1
1	Any	1	0
3	Any	3	0
n	Any	n	0

Cancel a specific delivery for an order

In this example, an order with a unique reference ORDER-PARTIALLY-DELIVERED is partially delivered as some items are no longer available. This order has two deliveries initially planned, one delivery with a unique reference TO-BE-DELIVERED for the items that can be delivered, and a second delivery with a unique reference TO-BE-CANCELLED for the items that are no longer available .

A delivery event CANCELLED_BEFORE_DESPATCH that uses the delivery reference TO-BE-CANCELLED is published in order to cancel the delivery that can not be delivered.

Steps:

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

Copy

Copied

{
  "order": {
    "orderRef": "ORDER-PARTIALLY-DELIVERED"
  },
  "deliveryRef": "TO-BE-DELIVERED"
}

Send the request to create the first delivery with the order information.
Expect a successful response with 204 No Content response code.
Update the body with the following JSON object that defines the second delivery of the order:

Copy

Copied

{
  "order": {
    "orderRef": "ORDER-PARTIALLY-DELIVERED"
  },
  "deliveryRef": "TO-BE-CANCELLED"
}

Send the request to create the second delivery with the order information.
Expect a successful response with 204 No Content response code.

Let's take a look at the initial state for this order before items become unavailable and a delivery is cancelled.

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

Copy

Copied

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-PARTIALLY-DELIVERED"
        },
        "parcel": {
            "deliveryRef": "TO-BE-CANCELLED",
            "deliveryLegs": [],
            "items": []
        },
        "trackingEvents": []
    },
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-PARTIALLY-DELIVERED"
        },
        "parcel": {
            "deliveryRef": "TO-BE-DELIVERED",
            "deliveryLegs": [],
            "items": []
        },
        "trackingEvents": []
    }
]

Two distinct parcel journeys are returned for this order. This is expected as initially the order is planned to be delivered in two separate deliveries.

During the processing of the order, some items are no longer available and requires the cancellation of the delivery with the unique delivery reference TO-BE-CANCELLED by the mean of a delivery event with the event code CANCELLED_BEFORE_DESPATCH.

Open the resource POST Add events for a delivery
Update the body with the following JSON object that defines the delivery event:

Copy

Copied

{
  "deliveryRef": "TO-BE-CANCELLED",
  "eventCode": "CANCELLED_BEFORE_DESPATCH",
  "eventDate": "2022-07-18T14:55:42.306Z",
  "eventTimeZone": "Europe/London"
}

Send the request to publish the delivery event.
Expect a successful response with 204 No Content response code.

Let's take a look at the parcel journeys for this order now that one delivery has been cancelled.

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

Copy

Copied

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-PARTIALLY-DELIVERED"
        },
        "parcel": {
            "deliveryRef": "TO-BE-DELIVERED",
            "deliveryLegs": [],
            "items": []
        },
        "trackingEvents": []
    }
]

Now that the delivery has been cancelled for the items no longer available, only one parcel journey is returned for the items that will be delivered.

Summary:

Number of deliveries	Number of delivery legs	Number of cancellation events	Number of Parcel Journeys
1	Any	0	1
1	Any	1	0
3	Any	1	2
n	Any	m	n-m

Cancel the delivery for a parcel

Similar to cancelling an order, a parcel that no longer needs to be shipped can be cancelled by means of a delivery leg event using the event code CANCELLED_BEFORE_DESPATCH and the tracking identifier of the parcel.

After this event is published, the parcel journey for the related parcel will no longer be returned by the API when querying using either the tracking identifier of the parcel or the order reference of the associated order if provided.

In this example, a parcel with tracking identifier PARCEL-CANCELLED and the order reference ORDER-WITH-PARCEL-CANCELLED is cancelled before despatch because the items are no longer available for shipping. A second parcel with tracking identifier PARCEL-SHIPPED is shipped with the available items for the order reference ORDER-WITH-PARCEL-CANCELLED.

Steps:

Open the resource POST Create or update a delivery leg .
Update the body with the following JSON object to create the delivery leg for the cancelled parcel:

Copy

Copied

{
  "trackingIdentifier": "PARCEL-CANCELLED",
  "order": {
    "orderRef": "ORDER-WITH-PARCEL-CANCELLED"
  }
}

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

Copy

Copied

{
  "trackingIdentifier": "PARCEL-SHIPPED",
  "order": {
    "orderRef": "ORDER-WITH-PARCEL-CANCELLED"
  }
}

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

Let's take a look at the parcel journeys for the order before the parcel is cancelled.

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-WITH-PARCEL-CANCELLED .
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"
        },
        "order": {
            "orderRef": "ORDER-WITH-PARCEL-CANCELLED"
        },
        "parcel": {
            "deliveryLegs": [
                {
                    "trackingIdentifier": "PARCEL-SHIPPED",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    },
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-WITH-PARCEL-CANCELLED"
        },
        "parcel": {
            "deliveryLegs": [
                {
                    "trackingIdentifier": "PARCEL-CANCELLED",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

Two parcel journeys for the order are returned in the API response. This is expected as the order was initially planned to ship using two parcels.

Let's cancel the parcel for which items are no longer available.

Open the resource POST Add tracking events to a delivery leg .
Update the body with the following JSON object:

Copy

Copied

{
  "trackingIdentifier": "PARCEL-CANCELLED",
  "eventCode": "CANCELLED_BEFORE_DESPATCH",
  "eventDate": "2022-08-19T05:27:23.006Z",
  "eventTimeZone": "Europe/London"
}

Send the request to publish the delivery leg event.
Expect a successful response with 204 No Content response code.

Let's take a look at the parcel journeys for the order now that one parcel has been cancelled.

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-WITH-PARCEL-CANCELLED .
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"
        },
        "order": {
            "orderRef": "ORDER-WITH-PARCEL-CANCELLED"
        },
        "parcel": {
            "deliveryLegs": [
                {
                    "trackingIdentifier": "PARCEL-SHIPPED",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

Only the parcel journey for the parcel that is shipped is returned when retrieving parcel journeys for the order.

Let's retrieve the parcel journey for the cancelled parcel using the tracking identifier of the parcel.

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 PARCEL-CANCELLED .
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

[]

No parcel journeys are returned for the parcel that has been cancelled.

Note: If a parcel is initially planned to be shipped using multiple carriers and multiple delivery legs have been created for it, only one event with the event code CANCELLED_BEFORE_DESPATCH that uses one of the tracking identifiers allocated to the parcel is required to cancel the entire delivery for this parcel. All associated delivery legs for this parcel will automatically be cancelled.

Number of parcels	Number of delivery legs	Number of cancellation events	Number of parcel journeys
1	1	0	1
1	2	0	1
1	Any	1	0
3	3	1	2
n	Any	r	n-r
n	Any	n	0