Track an order before parcel allocation

After an order has been created, information about the processing of the order is made available by means of a delivery. A delivery is used to enable a tracking experience before parcels have been allocated to a carrier. A delivery includes the same information as a delivery leg with the exception of information specific to a parcel such as tracking identifier or carrier code.

In this example, an order with the unique reference ORDER-PREALLOC-01 is made available by posting a delivery with a unique delivery reference DELIVERY-PREALLOC-01 before any parcels are allocated. A parcel with tracking identifier TRACK-PREALLOC-01 is added at a later stage once allocated to a carrier by posting a delivery leg that uses the same delivery reference DELIVERY-PREALLOC-01.

Steps:

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

{
  "order": {
    "orderRef": "ORDER-PREALLOC-01"
  },
  "deliveryRef": "DELIVERY-PREALLOC-01"
}

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

After a delivery has been created, the progress with processing the associated order can be tracked by retrieving the information in the shape of a parcel journey using the order reference.

• 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-PREALLOC-01 .
• 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:

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-PREALLOC-01"
        },
        "parcel": {
            "deliveryRef": "DELIVERY-PREALLOC-01",
            "deliveryLegs": [],
            "items": []
        },
        "trackingEvents": []
    }
]

A parcel journey is returned, similar to the parcel journey returned when providing parcel information using a delivery leg.

This parcel journey contains a pseudo parcel that includes the following fields:

• deliveryRef : the unique delivery reference from the delivery. This unique delivery reference is required when creating delivery legs to include parcel specific information.
• deliveryLegs : an array that will contain the delivery legs for the parcel.

Once the order has been processed and a parcel for shipping the order has been allocated to a carrier, a new delivery leg is created using the delivery reference DELIVERY-PREALLOC-01 and the tracking identifier TRACK-PREALLOC-01.

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

{
  "trackingIdentifier": "TRACK-PREALLOC-01",
  "carrierCode": "FASTWAY_AU",
  "deliveryRef": "DELIVERY-PREALLOC-01"
}

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

The parcel journey for the order is now enriched with information collected from both the delivery and the delivery leg.

• 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-PREALLOC-01 .
• Remove all other query parameters so that only the query parameter orderRef is retained.
• Send the request to retrieve 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:

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-PREALLOC-01"
        },
        "parcel": {
            "deliveryRef": "DELIVERY-PREALLOC-01",
            "deliveryLegs": [
                {
                    "carrierCode": "FASTWAY_AU",
                    "trackingIdentifier": "TRACK-PREALLOC-01",
                    "carrierDisplayName": "Fastway Australia",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

The parcel journey now includes a genuine parcel that has been enriched with the carrier information provided in the delivery leg.

Repeat the previous step, but retrieve the parcel journey for the order using the parcel's tracking identifier TRACK-PREALLOC-01 instead of the order reference.

The same parcel journey information is expected in both cases with information collected from both the delivery and the delivery leg.

Using deliveries in combination with delivery legs is a convenient way to provide information located in separate systems in order to deliver a great tracking experience unified within a parcel journey. As an example, an Order Management System provides order, product, customer information by integrating with the resource POST Create or update a delivery of the API, while a Warehouse Management System provides parcel and carrier information by integrating with the resource POST Create or update a delivery leg of the API.

Summary: