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 5 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.

	Condition	Value	Courier status
Delivered	Contains	Left with neighbour	Item has been left with neighbour TOM at the number (12)