> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get tracking
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](mailto:enterprise-solution@returnhelper.com).
Returns the carrier status and event history for a return label Return Helper generated for you. Pass the label's tracking number as `reference`.
The tracking number arrives in the [label generated webhook](/webhooks#label-result) — 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](#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_GERMANY`
* `RETURN_DHL_ECOMMERCE_DEU`
* `RETURN_DHL_ECOMMERCE_INTL_DEU`
* `ROYAL_MAIL`
* `RETURN_POSTMEN_RM_BIR`
* `RETURN_RM48_QRCODE_BIR_GBR`
* `FEDEX`
* `fedex_ground`
* `RETURN_FEDEX_GROUND_WA`
* `RETURN_FEDEX_GROUND_USCA`
* `RETURN_FEDEX_GROUND_TX`
* `UPS`
* `RETURN_UPS_SV_HKG`
## Reading the response
| Field | Notes |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `statusSlug` | Current status of the shipment — see [Status values](#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. |
All timestamps are ISO 8601 in UTC.
## 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](mailto: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 empty `reference` 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.
```json theme={null}
{
"correlationId": "0HNCJ2K1P9RQ4:00000003",
"meta": {
"status": 404,
"data": {},
"errorCode": null,
"error": {
"message": "Tracking service is temporarily unavailable."
}
}
}
```
## Related
* [Webhooks → Label Result](/webhooks#label-result) — where the tracking number is delivered.
* [Error codes](/reference/error-codes) — the full response envelope and error contract.
## OpenAPI
````yaml get /api/Tracking/GetTracking
openapi: 3.1.0
info:
title: Return Helper API
description: API documentation for Return Helper — covering User and Public endpoints.
version: 1.0.0
servers:
- url: https://api.returnshelper.com/uat/user
description: Sandbox — User API
- url: https://api.returnshelper.com/uat/public
description: Sandbox — Public API
- url: https://api.returnhelpercentre.com/v1/user
description: Production — User API
- url: https://api.returnhelpercentre.com/v1/public
description: Production — Public API
- url: https://api.returnhelperchina.com/user
description: Production — User API (China)
security:
- ApiKey: []
ApiToken: []
paths:
/api/Tracking/GetTracking:
get:
tags:
- Tracking
summary: Get tracking
operationId: ReturnUserApi_GetTracking
parameters:
- name: reference
in: query
required: true
description: Tracking number of a return label generated by Return Helper.
schema:
type: string
example: TRACK123456789
responses:
'200':
description: >-
Success — `data` carries the tracking detail. `events` is an empty
list when the carrier has not reported anything yet.
content:
application/json:
schema:
$ref: '#/components/schemas/General_UserGetTrackingReply'
'401':
description: >-
Authentication failed. Returned when the `x-rr-apikey` or
`x-rr-apitoken` header is missing or invalid. The body uses the
standard `ApiResponse` envelope with `meta.error.message` describing
the auth failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
security:
- ApiKey: []
ApiToken: []
servers:
- url: https://api.returnshelper.com/uat/user
description: Sandbox — User API
components:
schemas:
General_UserGetTrackingReply:
type: object
properties:
data:
$ref: '#/components/schemas/UserGetTrackingReply'
ApiResponse:
type: object
description: >-
Universal response envelope. Successful responses include the business
payload as additional top-level fields alongside `correlationId` and
`meta`. Failed responses (auth errors, validation errors) only populate
`correlationId` and `meta`, with `meta.errorCode` and `meta.error`
describing the failure.
properties:
correlationId:
type:
- string
- 'null'
description: >-
Unique correlation ID for tracing the request through Return Helper
systems.
meta:
$ref: '#/components/schemas/ApiResponseMeta'
UserGetTrackingReply:
type: object
properties:
id:
type:
- string
- 'null'
description: Identifier of the tracking record.
examples:
- b6e4a8b0-6f2e-4b7a-9c3d-8a1e2f3c4d5e
courierName:
type:
- string
- 'null'
description: >-
Human-readable carrier name. May be null for a newly registered
tracking number.
examples:
- USPS
trackingNumber:
type:
- string
- 'null'
description: Carrier tracking number.
examples:
- TRACK123456789
statusSlug:
type:
- string
- 'null'
description: >-
Current status of the shipment: PENDING, IN_TRANSIT, DELIVERED or
EXCEPTION.
examples:
- IN_TRANSIT
lastEventAt:
type:
- string
- 'null'
description: >-
ISO 8601 UTC timestamp of the most recent event. Null before the
first event arrives.
examples:
- '2026-07-29T08:00:00.000Z'
noFurtherUpdates:
type: boolean
description: True once no further tracking events are expected for this shipment.
events:
type: array
items:
$ref: '#/components/schemas/TrackingEventReply'
description: >-
Tracking events. Empty list when the carrier has not reported
anything yet.
ApiResponseMeta:
type: object
description: >-
Application-level metadata for every API response. Inspect `status` and
`errorCode` to detect soft-error responses (validation failures arrive
as HTTP 200 with `meta.status: 400`).
properties:
status:
type: integer
description: >-
Application-level status code. For successful operations this
mirrors the HTTP status (e.g. 200). For validation failures it
reports the logical status (e.g. 400) even though the wire HTTP
status is 200.
data:
type: object
additionalProperties:
type: string
description: Reserved free-form metadata key/value pairs. Usually empty.
errorCode:
type:
- string
- 'null'
description: >-
Machine-readable error code (e.g. `VALIDATION_FAILED`). Non-null
only when the operation failed.
error:
type: object
additionalProperties: true
description: >-
Field-level or message-level error detail keyed by request property
name. Empty object on success.
TrackingEventReply:
type: object
properties:
statusSlug:
type:
- string
- 'null'
description: >-
Status that applied at this event: PENDING, IN_TRANSIT, DELIVERED or
EXCEPTION.
examples:
- IN_TRANSIT
message:
type:
- string
- 'null'
description: >-
What happened, in the carrier's own wording. Free text — display or
log it, do not parse it.
examples:
- Arrived at facility
location:
type:
- string
- 'null'
description: >-
Where the event happened. Null when the carrier does not attach a
place to it.
examples:
- Los Angeles, CA 90001, US
eventAt:
type:
- string
- 'null'
description: ISO 8601 UTC timestamp of the event.
examples:
- '2026-07-29T08:00:00.000Z'
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-rr-apikey
description: Your API key
ApiToken:
type: apiKey
in: header
name: x-rr-apitoken
description: Your API token — keep this private
````