How Tracking API Works
This guide will delve into the significance of Voila Tracking Statuses, acquaint you with the Events Map, and reference the Mapped Events for each courier.
Last updated 4 months ago
Overview
The Tracking API conveniently monitors your shipments shipped through our partnered couriers at 6-hour intervals. It eliminates the need to navigate through intricate status updates that differ across various couriers. Voila simplifies these diverse statuses into a standardised set for your ease. These tracking statuses are readily accessible on your Shipments Page.
The tracking system employs a periodic tracking strategy for orders, attempting to track each order once every 6 hours. If the system encounters no response or a failed response during these tracking attempts, it initiates a 24-hour delay before making the next tracking attempt. This process is repeated up to 5 times for each shipment. In the event of a 'shipment not found' response, the tracking request is terminated.
Tracking Status
The Voila's tracking feature, known as the Tracking API, provides insight into the status of your parcels when they are sent using a tracked service through the courier. Depending on both the courier and the status of the parcel, you may encounter some of the following statuses, each explained below:
Status Code | Status | Description |
1 | Booked | This is the initial status after generating a label. It signifies that the courier has received the shipment data and you possess a label for it. |
2 | Collected | The courier has retrieved the parcel from the designated "ship_from" location. |
3 | At Hub | The parcel is within one of the courier's hubs, which may not be the final hub before ultimate delivery. |
4 | In Transit | The parcel resides within a courier van, either moving between hubs or potentially en route to the customer. |
5 | Out For Delivery | The parcel is en route to the customer in a courier van. |
6 | Failed Attempt | The courier attempted delivery but was unsuccessful for reasons like the customer being absent, lack of a suitable delivery location, or similar issues. |
7 | Delivered | The parcel has been successfully delivered to the customer. |
8 | On Hold | This status indicates an issue with the parcel, such as severe damage, security concerns, theft, the need for further instructions, or difficulty locating it. |
9 | Address Issue | The courier encounters problems delivering the parcel due to incorrect or problematic address details. |
10 | Returned To Sender | The parcel has been returned to the sender due to particular circumstances. |
11 | Tracking Expired | This applies to packages not delivered within the designated timeframe. We monitor packages for up to 15 days, and if a package remains undelivered beyond this period, we mark it as "Tracking Expired" to indicate the cessation of tracking. |
12 | Cancelled | The shipment has been voided or revoked. |
13 | Awaiting Customer Collection | The parcel is present at a hub or collection point, requiring the customer to pick it up. |
14 | Packed | The parcel has been successfully packed and is ready for dispatch. This status indicates that the items have been securely placed within the packaging, awaiting the courier's collection for the next phase of the delivery process. |
15 | Missing | This status indicates that the parcel is currently unaccounted for or cannot be located within the courier's system. It suggests a temporary loss or misplacement, and the courier is actively working to resolve the issue. This status does not imply a definitive loss but rather a momentary challenge in tracking the parcel's location. It may result from discrepancies in the tracking information or unforeseen circumstances during the transportation process. The courier is diligently investigating and will update the status accordingly once the parcel is located, or the issue is resolved. |
103 | Authentication Failed | This status arises when the Tracking API attempts to authenticate with the courier's API for tracking updates but encounters authentication difficulties. |
It's important to note that statuses other than "Booked" are not universally applicable across all couriers. Some couriers may lack tracking updates altogether, and not all couriers support every one of these statuses. For couriers with tracking support, "Booked" and "Delivered" statuses are typically supported, but other statuses may vary in support and availability.
Tracking Event Map
Within the Tracking API, we've implemented a system known as Tracking Events Mapping. As previously mentioned, various couriers utilise their distinct terminology to depict a parcel's status. With this mapping system, we seamlessly translate and define tracking statuses from our supported couriers into a standardised set of statuses utilised by the Tracking API.
Courier | Track Type | Condition | Value |
HermesCorporate | On Hold / Issue | Equals | carryover - parcel query |
HermesCorporate | At Hub | Equals | in the depot - stop return |
HermesCorporate | Failed Attempt | Equals | courier to reattempt |
DX | Delivered | Starts With | item has been delivered as requested and received by |
UPS | Awaiting Customer Collection | Starts With | the receiver requested this package to be held for pickup at the UPS facility |
DPD Local | On Hold / Issue | Starts With | parcel held (floor) |
Exelot | Booked | Equals | the parcel has been booked with the courier |
APC | Booked | Equals | the parcel has been booked with the courier |
HubEurope | In Transit | Starts With | in transit to the delivery depot |
UPS | In Transit | Equals | your package is in transit to the UPS facility |
DPD Local | Delivered | Contains | left with neighbour |
DPD Local | Failed Attempt | Starts With | unable to deliver, calling card left |
DPD | At Hub | Equals | forwarded to hub 4 depot |
Here's how it works:
Track Type: This refers to the status assigned to your parcel within Voila; it's the status to which your parcel's current state will be linked.
Value: The value signifies the tracking status received from the courier or a part of it.
Condition: Conditions are the rules governing the mapping process. We receive a "value" from the courier, and based on the specified "condition," we convert it into the appropriate "track type."
Equals: This implies that the "Value" matches the related "Track Type."
Starts With: If the courier's status begins with the specified "Value," Voila displays the corresponding "Track Type." For example:
Track type
Condition
Value
Courier status
Delivered
Starts with
Delivered, and received by
Delivered, received by NICOLE
Contains: When the courier's status contains the specified "Value," Voila associates it with the related "Track Type."
Track type
Condition
Value
Courier status
Delivered
Contains
Left with neighbour
Item has been left with neighbour TOM at the number (12)
This signifies that whenever the courier's status begins with "Delivered, received by," Voila will indicate the "Delivered" tracking status.
This tracking events mapping system streamlines the interpretation of various courier statuses, providing a consistent and understandable set of tracking updates.
Mapped Events for Couriers
The Tracking API features a mapping process where we take the various status updates provided by different couriers and transform them into a standardised format defined by Voila. We consistently maintain and enhance this list to ensure its accuracy. To explore the mapped events for a particular courier, locate the courier's name in the sections provided below. It will grant you access to that courier's specific mapped events list.
AmazonShipping
Track Type | Condition | Value |
Auth Failed | Equals | auth is empty. |
Auth Invalid | Equals | auth invalid. |
Awaiting Customer Collection | Equals | awaiting_customer_pickup |
Booked | Equals | ready_for_receive |
Delivered | Equals | DELIVERED |
Delivered | Equals | delivered |
In Transit | Equals | in_transit |
On Hold / Issue | Equals | status problem |
Tracking Expired | Equals | failed to track |
APC
Track Type | Condition | Value |
Address Issue | Starts With | check address |
At Hub | Starts With | at sending depot |
At Hub | Starts With | held at depot |
Booked | Starts With | label printed/done |
Collected | Starts With | collected from depot |
Delivered | Starts With | delivered |
Failed Attempt | Starts With | customer refused |
In Transit | Starts With | scan |
On Hold / Issue | Starts With | problem - not attempted |
DeutschePost
Track Type | Condition | Value |
At Hub | Equals | received & processed at the Deutsche Post mail terminal |
Auth Failed | Equals | auth is empty. |
Auth Invalid | Equals | auth invalid. |
Delivered | Equals | delivered |
Failed Attempt | Equals | Attempted Delivery |
FedEx
Track Type | Condition | Value |
Address Issue | Equals | delivery option requested |
At Hub | Equals | at FedEx origin facility |
TNT
Track Type | Condition | Value |
Booked | Equals | the parcel has been booked with the courier. |
Delivered | Equals | del |
In Transit | Equals | int |
On Hold / Issue | Equals | exc |
Tracking Expired | Equals | failed to track |
Tuffnells
Track Type | Condition | Value |
Address Issue | Equals | check address |
Booked | Equals | created by depot |
Next Steps & Support
📚 Need help? Explore more of our documentation, video walkthroughs or contact support.
With Voila, you will be set up for seamless, efficient shipping.
