Get tracking
curl --request GET \
--url https://api.returnshelper.com/uat/user/api/Tracking/GetTracking \
--header 'x-rr-apikey: <api-key>' \
--header 'x-rr-apitoken: <api-key>'import requests
url = "https://api.returnshelper.com/uat/user/api/Tracking/GetTracking"
headers = {
"x-rr-apikey": "<api-key>",
"x-rr-apitoken": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'x-rr-apikey': '<api-key>', 'x-rr-apitoken': '<api-key>'}
};
fetch('https://api.returnshelper.com/uat/user/api/Tracking/GetTracking', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.returnshelper.com/uat/user/api/Tracking/GetTracking",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-rr-apikey: <api-key>",
"x-rr-apitoken: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.returnshelper.com/uat/user/api/Tracking/GetTracking"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-rr-apikey", "<api-key>")
req.Header.Add("x-rr-apitoken", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.returnshelper.com/uat/user/api/Tracking/GetTracking")
.header("x-rr-apikey", "<api-key>")
.header("x-rr-apitoken", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.returnshelper.com/uat/user/api/Tracking/GetTracking")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-rr-apikey"] = '<api-key>'
request["x-rr-apitoken"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": {
"id": "b6e4a8b0-6f2e-4b7a-9c3d-8a1e2f3c4d5e",
"courierName": "USPS",
"trackingNumber": "TRACK123456789",
"statusSlug": "IN_TRANSIT",
"lastEventAt": "2026-07-29T08:00:00.000Z",
"noFurtherUpdates": true,
"events": [
{
"statusSlug": "IN_TRANSIT",
"message": "Arrived at facility",
"location": "Los Angeles, CA 90001, US",
"eventAt": "2026-07-29T08:00:00.000Z"
}
]
}
}{
"correlationId": "<string>",
"meta": {
"status": 123,
"data": {},
"errorCode": "<string>",
"error": {}
}
}Tracking
Get tracking
GET
/
api
/
Tracking
/
GetTracking
Get tracking
curl --request GET \
--url https://api.returnshelper.com/uat/user/api/Tracking/GetTracking \
--header 'x-rr-apikey: <api-key>' \
--header 'x-rr-apitoken: <api-key>'import requests
url = "https://api.returnshelper.com/uat/user/api/Tracking/GetTracking"
headers = {
"x-rr-apikey": "<api-key>",
"x-rr-apitoken": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'x-rr-apikey': '<api-key>', 'x-rr-apitoken': '<api-key>'}
};
fetch('https://api.returnshelper.com/uat/user/api/Tracking/GetTracking', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.returnshelper.com/uat/user/api/Tracking/GetTracking",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-rr-apikey: <api-key>",
"x-rr-apitoken: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.returnshelper.com/uat/user/api/Tracking/GetTracking"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-rr-apikey", "<api-key>")
req.Header.Add("x-rr-apitoken", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.returnshelper.com/uat/user/api/Tracking/GetTracking")
.header("x-rr-apikey", "<api-key>")
.header("x-rr-apitoken", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.returnshelper.com/uat/user/api/Tracking/GetTracking")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-rr-apikey"] = '<api-key>'
request["x-rr-apitoken"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": {
"id": "b6e4a8b0-6f2e-4b7a-9c3d-8a1e2f3c4d5e",
"courierName": "USPS",
"trackingNumber": "TRACK123456789",
"statusSlug": "IN_TRANSIT",
"lastEventAt": "2026-07-29T08:00:00.000Z",
"noFurtherUpdates": true,
"events": [
{
"statusSlug": "IN_TRANSIT",
"message": "Arrived at facility",
"location": "Los Angeles, CA 90001, US",
"eventAt": "2026-07-29T08:00:00.000Z"
}
]
}
}{
"correlationId": "<string>",
"meta": {
"status": 123,
"data": {},
"errorCode": "<string>",
"error": {}
}
}This is an Enterprise-only feature, enabled only for Return Helper Enterprise customers. To learn more about pricing for this service, contact enterprise-solution@returnhelper.com.
reference.
The tracking number arrives in the label generated webhook — cache it on your side as labels are created, then call this endpoint whenever you need the current status.
What can be looked up
Tracking covers return labels created with one of the supported service types. A tracking number from any other service type, or from a label created before this feature went live, returns a not-found error rather than an empty result.Supported service types
DHL_GERMANYRETURN_DHL_ECOMMERCE_DEURETURN_DHL_ECOMMERCE_INTL_DEUROYAL_MAILRETURN_POSTMEN_RM_BIRRETURN_RM48_QRCODE_BIR_GBRFEDEXfedex_groundRETURN_FEDEX_GROUND_WARETURN_FEDEX_GROUND_USCARETURN_FEDEX_GROUND_TXUPSRETURN_UPS_SV_HKG
Reading the response
| Field | Notes |
|---|---|
statusSlug | Current status of the shipment — see Status values. Each entry in events carries the status that applied at that point. |
events | Tracking events, each with statusSlug, message, location and eventAt. message is the carrier’s own wording for what happened. location is null for events the carrier does not attach a place to. Empty list when the carrier has not reported anything yet. |
lastEventAt | Time of the most recent event, null before the first one arrives. |
noFurtherUpdates | true once no further events are expected for this shipment. Use it to stop polling. |
courierName | Human-readable carrier name. May be null for a newly registered tracking number. |
id | Identifier of the tracking record. |
Status values
statusSlug | Meaning |
|---|---|
PENDING | The tracking number is registered; the carrier has not reported anything yet. |
IN_TRANSIT | The carrier is moving the parcel. |
DELIVERED | The carrier reported the parcel as delivered. |
EXCEPTION | The tracking number could not be registered for tracking. No events will arrive for it — contact support@returnhelper.com if you need the shipment traced. |
message is free text from the carrier — display it or log it, but do not parse it or branch on it. Branch on statusSlug instead, and let an unrecognised value fall through to a default rather than failing.Errors
A missing or emptyreference fails validation: HTTP 200, meta.status 400, meta.errorCode VALIDATION_FAILED, with the message under meta.error.reference.
Every other failure comes back as HTTP 200 with meta.status 404, meta.errorCode null, and a human-readable meta.error.message:
- The tracking number is unknown, or the tracking service could not accept it — the message explains which.
Tracking service is temporarily unavailable.— the tracking service could not be reached. The reference may still be valid; retry later.
{
"correlationId": "0HNCJ2K1P9RQ4:00000003",
"meta": {
"status": 404,
"data": {},
"errorCode": null,
"error": {
"message": "Tracking service is temporarily unavailable."
}
}
}
Related
- Webhooks → Label Result — where the tracking number is delivered.
- Error codes — the full response envelope and error contract.
Authorizations
Your API key
Your API token — keep this private
Query Parameters
Tracking number of a return label generated by Return Helper.
Response
Success — data carries the tracking detail. events is an empty list when the carrier has not reported anything yet.
Show child attributes
Show child attributes