Skip to main content
GET
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.
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 — 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_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

All timestamps are ISO 8601 in UTC.

Status values

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.

Authorizations

x-rr-apikey
string
header
required

Your API key

x-rr-apitoken
string
header
required

Your API token — keep this private

Query Parameters

reference
string
required

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.

data
object