# Tracking API # How Tracking API Works ## **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**](https://shipping-documentation.despatchcloud.app/books/shipments/page/shipments).

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.

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. ### **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

- This signifies that whenever the courier's status begins with "Delivered, received by," Voila will indicate the "Delivered" tracking status. - **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)

- If the courier's status includes the phrase "Left with neighbour," Voila will display 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
Booked	Equals	the parcel has been booked with the courier.
Booked	Starts With	the parcel has been booked with the courier.
Delivered	Equals	DELIVERED
Delivered	Equals	delivered
Delivered	Starts With	delivered
Failed Attempt	Equals	delivery\_attempted
Failed Attempt	Equals	rejected
In Transit	Equals	in\_transit
In Transit	Equals	transit
On Hold / Issue	Equals	carrier\_cancelled\_pickup
On Hold / Issue	Equals	lost
On Hold / Issue	Equals	pickup\_cancelled
On Hold / Issue	Equals	undeliverable
Out for Delivery	Equals	OUT\_FOR\_DELIVERY
Out for Delivery	Equals	out\_for\_delivery
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
At Hub	Starts With	at hub
At Hub	Starts With	at depot
At Hub	Starts With	at delivery depot
At Hub	Starts With	book-in required
Booked	Starts With	label printed/done
Booked	Starts With	manifested
Booked	Starts With	ready to print
Booked	Equals	the parcel has been booked with the courier.
Cancelled	Starts With	cancelled
Collected	Starts With	collected/picked up
Collected	Starts With	collected from depot
Delivered	Starts With	delivered
Delivered	Starts With	left as instructed
Delivered	Starts With	left with neighbour
Failed	Starts With	failed
Failed Attempt	Starts With	customer refused
Failed Attempt	Starts With	closed/carded
Failed Attempt	Starts With	not received on the trunk
In Transit	Starts With	scan
In Transit	Starts With	updated/resolved
On Hold / Issue	Starts With	queue
On Hold / Issue	Starts With	problem - not attempted
On Hold / Issue	Starts With	damaged
On Hold / Issue	Starts With	missing
On Hold / Issue	Starts With	not received in the depot
On Hold / Issue	Starts With	intercom - no access
On Hold / Issue	Starts With	delayed by weather
On Hold / Issue	Starts With	customer re-arranged
On Hold / Issue	Equals	vehicle breakdown
Out for Delivery	Starts With	out for delivery
Returned to Sender	Starts With	return

#### **DeutschePost**

Track Type	Condition	Value
At Hub	Equals	received & processed at the Deutsche Post mail terminal
At Hub	Starts With	arrived
Auth Failed	Equals	auth is empty.
Auth Invalid	Equals	auth invalid.
Booked	Equals	shipment information uploaded to Deutsche Post
Booked	Equals	the parcel has been booked with the courier.
Delivered	Equals	delivered
Failed Attempt	Equals	Attempted Delivery
Failed Attempt	Equals	attempted delivery
Failed Attempt	Equals	failed to track
In Transit	Starts With	departed
On Hold / Issue	Starts With	held
Returned to Sender	Equals	return to Deutsche Post return centre

#### **DGInternational**

Track Type	Condition	Value
Address Issue	Starts With	we tried to deliver your parcel but were told you have moved
Address Issue	Starts With	sorry we were unable to locate your property
Address Issue	Starts With	we need some more information about your address
At Hub	Starts With	your parcel has arrived at your local depot
At Hub	Starts With	your parcel is at our sorting centre
At Hub	Equals	your parcel is at our national hub
At Hub	Equals	your parcel is at your local depot
At Hub	Equals	your parcel has arrived at your local depot (jersey c/i service centre)
At Hub	Starts With	your parcel has arrived at your local depot (guernsey c/i service centre)
Awaiting Customer Collection	Starts With	you have chosen to collect your parcel
Awaiting Customer Collection	Equals	please arrange to collect your parcel from our depot by using the manage your parcel feature above
Booked	Equals	the parcel has been booked with the courier.
Booked	Equals	your parcel will be with us soon
Collected	Starts With	you have collected your parcel
Collected	Equals	we have collected your parcel
Delivered	Equals	your parcel has been delivered to a safe place
Delivered	Starts With	your parcel has been delivered
Delivered	Starts With	delivered. unable to sign
Failed Attempt	Starts With	we tried to deliver your parcel but it was refused at the door
Failed Attempt	Starts With	we tried to deliver your parcel but couldn't access your property
Failed Attempt	Starts With	we tried to deliver your parcel but were unable to gain access to the property.
Failed Attempt	Starts With	sorry we couldn't deliver
Failed Attempt	Starts With	sorry we missed you
Failed Attempt	Equals	we came to collect but the premises were closed.
Failed Attempt	Equals	we tried to deliver but the premises were closed.
In Transit	Starts With	our vehicle has been delayed on the way to your local depot
In Transit	Equals	your parcel was delayed on its way to your local depot.
In Transit	Equals	your parcel is on its way, but we are experiencing a delay in getting to you.
In Transit	Starts With	thank you, we have received your new address
In Transit	Starts With	your parcel is on the way but there could be a short delay.
In Transit	Starts With	thanks for choosing a new date
In Transit	Equals	your parcel is in transit
In Transit	Starts With	your parcel is on its way
In Transit	Starts With	we have updated your parcel with your neighbour preferences
In Transit	Starts With	your parcel is being loaded
In Transit	Equals	your parcel has left the UK and is on its way
On Hold / Issue	Starts With	oh no!
On Hold / Issue	Starts With	your parcel arrived with us in need of repackaging
On Hold / Issue	Equals	we are waiting for the retailer to provide further details. check back for updates
On Hold / Issue	Starts With	your parcel from the sender has arrived damaged and we are unable to deliver
On Hold / Issue	Starts With	due to the parcel condition/contents, we are unable to deliver
On Hold / Issue	Equals	your parcel is with us, but there could be a short delay. please check back for tracking updates
On Hold / Issue	Equals	in customs. you may experience a short delay while additional information is requested
On Hold / Issue	Starts With	your parcel will be delayed while we verify the safety of the contents. please check back for tracking updates.
On Hold / Issue	Equals	we have not yet received your parcel. please contact the sender with any queries.
On Hold / Issue	Equals	cleared export customs check
On Hold / Issue	Equals	your parcel is with the customs
On Hold / Issue	Starts With	we have your parcel but we're waiting for some additional information from the sender. please contact the sender with any queries.
On Hold / Issue	Equals	there has been a short delay. please bear with us and check back for updates
Out for Delivery	Starts With	your parcel is with one of our drivers for delivery
Out for Delivery	Starts With	your parcel has been scheduled for
Returned to Sender	Starts With	your parcel has been returned to your sender

#### **DHLParcelUK**

Track Type	Condition	Value
Address Issue	Equals	delayed
At Hub	Equals	at delivery location
At Hub	Equals	received at the local parcel shop
Booked	Equals	awaiting collection
Booked	Equals	booked/awaiting collection
Booked	Equals	the parcel has been booked with the courier.
Collected	Equals	collected
Delivered	Equals	customer collected from a local parcel shop
Delivered	Equals	delivered
Delivered	Equals	part delivered
Failed Attempt	Equals	delivery attempted
On Hold / Issue	Equals	awaiting delivery to the local parcel shop
On Hold / Issue	Equals	delivery attempted to the local parcel shop
On Hold / Issue	Equals	delivery rearranged by the recipient
On Hold / Issue	Equals	please call
Out for Delivery	Equals	out for delivery

#### **Exelot**

Track Type	Condition	Value
At Hub	Equals	package in the sorting centre
At Hub	Equals	package going to the sorting centre
Booked	Equals	the parcel has been booked with the courier.
Booked	Equals	package details received
Delivered	Equals	delivered
In Transit	Equals	package released from customs
In Transit	Equals	in the outbound customs process
In Transit	Equals	package flight details received
On Hold / Issue	Equals	in tracing

#### **FedEx**

Track Type	Condition	Value
Address Issue	Equals	delivery option requested
At Hub	Equals	at FedEx origin facility
At Hub	Equals	arrived at the FedEx location
At Hub	Equals	at the local FedEx facility
At Hub	Equals	at destination sort facility
At Hub	Equals	at local facility
At Hub	Equals	arrived at the FedEx hub
At Hub	Equals	departed FedEx hub
Auth Invalid	Equals	invalid argument supplied for foreach()
Booked	Equals	Shipment information sent to FedEx
Booked	Equals	the parcel has been booked with the courier.
Booked	Equals	delivery option updated
Cancelled	Equals	shipment cancelled by the sender
Collected	Equals	picked up
Delivered	Equals	delivered
Failed	Equals	failed to track
In Transit	Equals	on the FedEx vehicle for delivery
In Transit	Equals	in transit
On Hold / Issue	Equals	shipment exception
On Hold / Issue	Equals	delivery exception
On Hold / Issue	Equals	clearance delay - import
On Hold / Issue	Equals	international shipment release - import
On Hold / Issue	Equals	clearance in progress
On Hold / Issue	Equals	delivery option request cancelled
On Hold / Issue	Equals	hold at location request accepted
On Hold / Issue	Equals	local delay
On Hold / Issue	Equals	operational delay
On Hold / Issue	Equals	delay
On Hold / Issue	Starts With	clearance delay
Out for Delivery	Equals	departed FedEx location
Out for Delivery	Equals	left FedEx origin facility
Out for Delivery	Equals	ready for recipient pickup
Out for Delivery	Equals	out for delivery
Returned to Sender	Equals	returning the package to the shipper

#### **Parcelforce**

Track Type	Condition	Value
Address Issue	Equals	address problem (unable to locate premises)
Address Issue	Equals	address problems (insufficient address)
Address Issue	Equals	address problem (insufficient address)
Address Issue	Equals	address problems (unable to locate premises)
Address Issue	Equals	address problems
Address Issue	Equals	address problem resolved
Address Issue	Equals	addressee requested delivery to the new address
Address Issue	Equals	address problem - insufficient address
Address Issue	Equals	address problem - sender contacted
Address Issue	Equals	address problem - require sender instruction
Address Issue	Equals	empty postcode.
At Hub	Equals	received at the delivery depot
At Hub	Equals	prepared for export by air
At Hub	Equals	prepared for export
At Hub	Equals	sorted for export
At Hub	Equals	delivery scheduled
Awaiting Customer Collection	Equals	addressee to collect from the post office
Awaiting Customer Collection	Equals	addressee advised to collect from depot
Awaiting Customer Collection	Equals	addressee to collect from the depot
Awaiting Customer Collection	Equals	addressee advised to collect from parcelshop
Awaiting Customer Collection	Equals	available for collection - SMS sent to the recipient
Awaiting Customer Collection	Equals	addressee advised to collect from post office
Awaiting Customer Collection	Equals	addressee advised to pick it up from the post office
Booked	Equals	the parcel has been booked with the courier.
Cancelled	Equals	parcel disposed of
Collected	Equals	collected
Collected	Equals	sorted
Delivered	Equals	delivered
Delivered	Equals	collected by addressee
Delivered	Equals	collected by the addressee
Delivered	Starts With	delivered to neighbour
Delivered	Contains	delivered to a safe place
Delivered	Equals	delivered to a neighbour
Failed	Equals	parcel missing/cannot be located
Failed Attempt	Equals	attempted delivery
Failed Attempt	Equals	delivery attempted - premises unoccupied
Failed Attempt	Equals	delivery attempted - SMS sent to the recipient
Failed Attempt	Equals	second delivery attempt scheduled
Failed Attempt	Equals	returned to depot
Failed Attempt	Equals	delivery attempted - refused by the addressee
Failed Attempt	Equals	delivery attempted
Failed Attempt	Equals	advised not received
Failed Attempt	Equals	delivery attempted - premises closed
Failed Attempt	Equals	attempted delivery - premises closed
Failed Attempt	Equals	collection attempted - customer not available
In Transit	Equals	handed to parcelforce driver
In Transit	Equals	on route to the delivery depot
In Transit	Equals	on route to the hub
In Transit	Equals	exported from the UK
In Transit	Equals	forwarded to the correct delivery depot
In Transit	Equals	arrived in the destination country
In Transit	Equals	tracked in the destination country
In Transit	Equals	secure parcel tracked out of the depot
In Transit	Equals	released from customs
In Transit	Equals	handed to the delivery partner
In Transit	Equals	received in the destination country
In Transit	Equals	despatched to the UK
In Transit	Equals	forwarded to the correct depot
On Hold / Issue	Equals	damage observed and noted
On Hold / Issue	Equals	delivery delayed today - SMS sent to the recipient
On Hold / Issue	Equals	held in the depot - customs charges outstanding
On Hold / Issue	Equals	held in depot
On Hold / Issue	Equals	awaiting customs clearance
On Hold / Issue	Equals	damage repaired
On Hold / Issue	Equals	held at the depot - packaging damaged
On Hold / Issue	Equals	held at the depot - parcel damaged
On Hold / Issue	Equals	held in the depot for re-delivery
On Hold / Issue	Equals	held in the depot - premises closed
On Hold / Issue	Equals	delivery delayed (to be rescheduled) - SMS sent to the recipient
On Hold / Issue	Equals	addressee requested a later delivery
On Hold / Issue	Equals	received at the incorrect delivery depot
On Hold / Issue	Equals	unable to deliver - adverse weather
On Hold / Issue	Equals	secure pin validation is not possible
On Hold / Issue	Equals	redelivery scheduled
On Hold / Issue	Equals	2nd delivery customs data
On Hold / Issue	Equals	held at customs - incorrect documents
On Hold / Issue	Equals	delivery delayed and rescheduled
On Hold / Issue	Equals	awaiting payment of charges
On Hold / Issue	Equals	time exceeded
On Hold / Issue	Equals	attempted delivery - item damaged
On Hold / Issue	Starts With	unexpected data found.
On Hold / Issue	Equals	failed to track
On Hold / Issue	Equals	we could not fetch form information.
On Hold / Issue	Equals	we could not fetch information.
Out for Delivery	Equals	out for delivery
Out for Delivery	Equals	your delivery today - SMS sent to the recipient
Out for Delivery	Equals	prepared for delivery
Out for Delivery	Equals	parcel despatched - SMS sent to the recipient
Returned to Sender	Equals	not collected by addressee - return to sender
Returned to Sender	Equals	returned to sender
Returned to Sender	Equals	delivered back to the sender
Returned to Sender	Equals	return to sender in the UK
Returned to Sender	Equals	return to sender in the UK - not collected by addressee

#### **RoyalMail**

Track Type	Condition	Value
Booked	Equals	the parcel has been booked with the courier.
Booked	Starts With	the parcel has been booked with the courier.
Booked	Equals	info received
Collected	Equals	pickup
Delivered	Equals	delivered
Failed Attempt	Equals	undelivered
Failed Attempt	Equals	not found
In Transit	Equals	transit
On Hold / Issue	Equals	exception
Tracking Expired	Equals	expired

#### **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
Booked	Equals	the parcel has been booked with the courier.
Booked	Equals	book in
Cancelled	Equals	closed
Delivered	Equals	delivered
Failed	Equals	failed - other reason
Failed Attempt	Equals	card left
In Transit	Equals	in transit - awaiting pod
In Transit	Equals	in transit - lan
In Transit	Equals	in transit - per
On Hold / Issue	Equals	road closed
On Hold / Issue	Equals	held at the delivery depot
On Hold / Issue	Equals	refused not damaged
On Hold / Issue	Equals	re-delivery charge incurred
On Hold / Issue	Starts With	breakdown
On Hold / Issue	Starts With	non-p1 48-hour delivery
Out for Delivery	Equals	out to deliver