Labelling

Labelling is an important step in the order lifecycle. Labels are carrier-specific, and must be generated with the correct information that each individual carrier needs to be able to transport the order to the right place.

Label latency

When you create an order, producing the label is the final step in the process. The steps in the process to create an order are:

  1. Send a request to the order API to retrieve carrier options, which queries a range of external carrier APIs.
  2. Allocate the order to a carrier based on allocation settings, and receive a 200 response from the external carrier API.
  3. Send a request to the label API to create the label as a PDF file, and store the file in cloud storage.
  4. Retrieve the label from cloud storage, and send it to a printer.

Each of these steps takes time to process, with some steps taking longer than others. For example, the order request and allocation steps can take some time because they need to interact with external carrier APIs.

There are a range of factors to take into account when measuring label creation latency. Some of these things are within your control to adjust, and others are not.

  • Carrier selection
  • Freight type
  • Package allocation
  • Network traffic

Shippit is constantly working on ways to improve the speed of these APIs, and how they work with external carrier APIs, so you might find that your label latency improves over time.

Labelling errors

If you request a label with the GET /orders/{tracking_number}/label endpoint, and the order is not available to label, the API responds with a 422 Unprocessable Content error. There are several different reasons that you can get this response. They are evaluated in the order given on this page, so if one of these situations matches, it responds with that error without checking further.

label_failed_order_processing

This happens when the order has a status of processing. Order can have this status when there has been a request to update the order, using the Shippit UI, which has resulted in re-quoting and that has not yet completed yet. Updating the pickup, delivery, courier, product fields, or parcel fields can cause re-quoting.

label_failed_missing_courier

This happens if a carrier can’t be allocated to an order, and can happen when the order is created, or updated. In most cases, an order can fall back to the first enabled carrier that offers the requested service level. Sometimes, this fallback doesn’t work, such as an international order where there is no available international carrier. In this case, any labelling request for the order returns this error.

label_failed_invalid_quote

This error occurs when an order has an invalid quote.

Quotes are considered invalid if:

  • There is no courier allocated
  • The quote is $0
  • There is no quote
  • There are any errors on the order

This can also happen if the order has a $0 quote, the allocated courier can confirm a $0 quote, and the rules engine filtered the quote.

label_failed_rules_engine

This error occurs if the order was allocated to a plain label carrier, and the order got some quotes, but because of the rules setup by the merchant in the rules engine, it was filtered out.

label_failed_still_generating

This error happens if the allocated carrier can generate label asynchronously. In this case, the labelling process starts in the background, and result in this error.

Currently, this only applies to:

  • Australia Post eParcel International
  • DHL eCommerce

label_failed_failed_request

This error occurs if the labelling process was started but then failed for some reason. This usually happens because of some external dependency that has failed. For example, if a carrier can’t generate the label

label_failed_tracking_order

If the order has the tracking_only parameter set, any request for a label results in this error.

order_not_available_to_label

This error occurs when none of the previous errors match, but the label is still not available for the order.

Avoiding label request timeouts

If you use an automated order management system, you might find that your label requests time out with a 422 Unprocessable response. There are a range of circumstances that can trigger this response. In some cases, the best workflow is to try and retrieve the label again.

In general, your workflow should create an order, wait one second, then poll for the label. If you receive a 422 error response with one of these messages, and the retry count is less than 8, continue waiting, then try polling for the label again:

  • order_not_available_to_label
  • label_failed_still_generating

If you receive a 422 error response with any other message, check the list in this section to find out next steps.

If the label continues to return a 422 error response, cancel the order using the DELETE /orders/{tracking_number} endpoint, and create the order again.