Tracktry API

Tracktry API

Get API key

In order to use this API you will need to generate a Tracktry API key in the API Keys.

The base URL

Note : "http" is also supported.


In order to verify and authenticate your application (e.g. your site), all of the requests that you make to the API must include your unique Tracktry API Key header (Tracktry-Api-Key), which you can generate and/or find in the API Keys.

Content-Type: application/json
Tracktry-Api-Key: YOUR_API_KEY

List of Tracking Statuses

String Description
pending New shipments added that are pending to track
notfound Item is not found at this moment.
transitItem has shipped from originating and is en route to its destination
pickupItem is out for delivery or arrived at local facility, you may schedule for delivery or pickup
deliveredThe shipment was delivered sucessfully.
undeliveredCarrier attempted to deliver but failed, and usually leaves a notice and will try to delivery again.
exceptionItem might undergo unusual shipping condition, this may due to several reasons, most likely item was returned to sender, customs issue, lost, damaged etc.
expired Item was in transportation period for a long time still has no delivered results.

Notfound SubStatus Description
not found001Information Received/info received. The package is about to be picked up.
not found002There is no tracking information for this package.

Exception SubStatus Description
exception001Tracking number added more than ** with no tracking info, marked as "Exception".
exception002Package in transit for ** with no marked as "Exception".
exception003Tracking number added more than ** but not delivered, marked as "Exception".
exception004The package is unclaimed.
exception005The package was sent back to the sender.
exception006The package is retained by customs because it's prohibited goods.
exception007The package is damaged, lost or discarded.
exception008The package is canceled before delivering.

API Parameter Return List

code Meta.code
type Meta.type
message Meta status description
id A random data generated by Tracktry to identify a tracking
tracking_number Package tracking number
carrier_code Courier code
status Package status
created_at Time a tracking number was added
updated_at Latest time a tracking number was updated
order_create_time Time an order was created
title Product title
order_id Order ID
comment Your remark to a shipment
customer_name Customer name
customer_email Customer email
original_country Origin country name
singed_by Recipient name
lastEvent Latest tracking info
lastUpdateTime Time of latest tracking info
destination_country Destination country name
itemTimeLength Transportation time of a shipment
stayTimeLength Total days no update since the time last tracking info appeared
origin_info Tracking info from origin courier
ItemReceived Time of a first tracking info appeared
ItemDispatched Time of departure from outward office of exchange
DepartfromAirport Time of arrival at airport
ArrivalfromAbroad Time of arrival at destination country
CustomsClearance Time a package was handed over to customs
DestinationArrived Time of arrival at delivery office
weblink Courier official website link
phone Courier phone number
trackinfo Details of package tracking info
Date Time of a specific piece of tracking info
StatusDescription Main contents of a piece of tracking info
Details Location info appeared in a specific piece of tracking info
destination_info Tracking info from destination courier

Typical Server Responses

We will respond with one of the following status codes.

200 Success The request was successful (some API calls may return 201 instead).
201 Created The request was successful and a resource was created.
202 Bad Request The request was successful but exceeding the limit.
401 Unauthorized Authentication failed or user does not have permissions for the requested operation.
4001 Unauthorized Invalid API key. Check
4002 Unauthorized API key has been deleted. Check
4012 Bad Request The request could not be understood or was missing required parameters.
4013 Bad Request Tracking_number is required.
4014 Bad Request The value of `tracking_number` is invalid.
4015 Bad Request The value of `carrier_code` is invalid. Check courier code
4016 Bad Request Tracking already exists.
4017 Bad Request Tracking does not exist.
4018 Bad Request Due to overload risks this feature requires custom activation. Contact [email protected] for more information.
4019 Bad Request Your balance is not enough, please recharge in time, free account can add up to 500 single numbers per month.
4020 Bad Request Up to 200 at a time
4021 Bad Request Your remaining balance is not enough, so you can not call the API request data. Purchase
4031 No Content The request was successful but the response is empty. Please try POST /trackings/post and then GET /trackings/get
4032 No Content Cannot detect courier. Assign your shipment a courier instead of by auto detection. Get courier code
4033 No Content The value of `status` is invalid.
402 Payment Required Payment required.
403 Forbidden Access denied.
404 Not Found Resource was not found.
405 Method Not Allowed Requested method is not supported for the specified resource.
409 Conflict The request could not be completed due to a conflict.
429 Too Many Requests Exceeded API limits. Pause requests, wait two minute, and try again.
500 Server error
503 Service Unavailable The service is temporary unavailable (e.g. scheduled Platform Maintenance). Try again later.

Request Rate Limiting

We do enforce a small amount of rate limiting. Please be aware that should you exceed these limits, you will receive a 429 error.

  • POST /trackings/realtime         Real-time tracking: each IP, maximum 3 requests per second.
  • GET /trackings/get                     List all trackings; each IP, maximum 1 request with up to 2000 trackings per second.