`GET` /2026-05/cloud/label/tracking/{id}

Method: GET

URL:

Sandbox URL:

Description: Retrieves shipment tracking information and tracking checkpoints.

Parameters required to be sent

Parameter	Description	Type
`id`	Label ID.	Long, Required

Response Parameters

Response data contains:

Parameter	Description	Type
`tracking_courier`	Carrier code. Returns `null` until ZhenHub allocates a carrier.	String or null
`tracking_number`	Carrier tracking number. Returns `null` until the carrier tracking number is allocated.	String or null
`outbound_time`	Optional outbound timestamp when available from the shipment source. Availability and semantics may vary by carrier; do not universally treat this field as the dispatch timestamp.	Date Time or null
`delivered_time`	Shipment delivery time when reported by the tracking provider.	Date Time or null
`checkpoints`	Tracking event history returned by the carrier, sorted in reverse chronological order (latest event first).	Array
`local_time`	Tracking event timestamp normalized to UTC and returned in ISO 8601 format.	Date Time (ISO 8601 UTC)
`sub_status`	Normalized detail for this checkpoint. See Checkpoint sub-status reference. Returns `null` when no supported detail can be identified.	String or null
`details`	Location or tracking details.	String
`description`	Tracking event description.	String
`status`	Normalized checkpoint status. See Checkpoint status reference.	String

Checkpoint status reference

checkpoints[].status provides a normalized view of the shipment event. It is not the carrier's original event code. Use description for the carrier-provided event details. Each checkpoint describes the event at its own local_time, not a permanent shipment-level condition. An earlier exception remains in the history even when a later event confirms recovery or successful delivery.

Integration guidance

Status values use lowercase snake_case and are listed below in typical shipment lifecycle order. Availability varies by carrier and shipment.

Outbound time

No, it is not safe to universally treat outbound_time as the dispatch timestamp. The field is optional, its availability and source semantics vary by carrier, and it may be null even when tracking checkpoints are available. Use checkpoints to determine shipment progression unless a carrier-specific integration contract defines outbound_time more precisely.

Value	Stage	Description
`information_received`	Pre-transit	ZhenHub has received the shipment information and the shipping label has been created, but the carrier may not yet have possession of the package.
`in_transit`	In transit	The carrier has accepted the shipment and it is moving through the carrier network.
`out_for_delivery`	Last mile	The shipment is with the local courier for final delivery.
`available_for_pickup`	Last mile	The shipment is available for collection at a designated pickup point. Retention periods vary by carrier.
`delivery_attempt_failed`	Delivery issue	This delivery attempt was unsuccessful. The issue may be temporary, and a later attempt may succeed. This event does not establish a final delivery failure or return.
`delivered`	Delivered	The shipment has been successfully delivered.
`delivered_with_exception`	Delivered with exception	This event records delivery with an abnormal condition associated with that delivery. Review `description` for details. An earlier failed attempt or exception alone does not make a later successful delivery `delivered_with_exception`.
`exception`	Exception	This event reports an exception, such as a return, customs issue, loss, or damage. It does not by itself establish a permanent or final outcome. Some exceptions are temporary; review `description` and subsequent checkpoints to determine what happened next.
`disposed`	Terminal exception	The shipment has been abandoned, destroyed, or otherwise disposed of.
`expired`	Exception	The shipment has remained in transit for an extended period without a delivery result.
`unknown`	Unknown	The status could not be determined from the available carrier information.

Checkpoint sub-status reference

sub_status supplements status with a standardized event detail. It describes only the checkpoint at its local_time; it is not a persistent shipment-level exception. Carrier-specific event codes are not exposed. Use these stable lowercase snake_case values for automation and description for the carrier's explanation.

Value	Associated status	Meaning
`recipient_unavailable`	`delivery_attempt_failed`	The recipient was absent, unavailable, or could not be contacted for this attempt.
`recipient_refused`	`delivery_attempt_failed`	The recipient refused delivery. This alone does not establish a return.
`address_issue`	`delivery_attempt_failed` / `exception`	The carrier explicitly reported an incorrect, incomplete, or invalid address.
`redelivery_pending`	`delivery_attempt_failed`	Another delivery attempt is pending or has been arranged.
`weather_disruption`	`delivery_attempt_failed` / `exception`	The carrier explicitly reported that weather, including a typhoon, disrupted delivery or transport. The associated status follows the event stage.
`customs_issue`	`exception`	An explicit customs exception was reported; review `description` for the specific requirement.
`returning_to_sender`	`exception`	The carrier explicitly reported a return process. This does not confirm receipt by the sender.
`shipment_cancelled`	`exception`	Shipment cancellation was reported.
`shipment_damaged`	`exception` / `delivered_with_exception`	The carrier explicitly reported damage to the shipment.
`shipment_lost`	`exception`	The carrier explicitly reported loss of the shipment.
`partially_delivered`	`exception`	Only part of the shipment was delivered. This does not establish successful delivery of the entire shipment.

These are cross-carrier normalized reasons, not a carrier event catalogue. Availability depends on reliable source information; support for a value does not mean every carrier supplies it. A failed attempt or exception alone does not establish a return. Carrier-specific distinctions remain in description.

sub_status is nullable. Normal events, insufficient information, unsupported reasons, and unreliable mappings return null. This does not mean no issue occurred: fall back to status and description. Clients must tolerate future unknown status and sub_status values without exhaustive enum assumptions.

New values require cross-carrier relevance, materially different client automation, a need beyond status plus description, reliable mapping, and stable public semantics. Otherwise use null and preserve the explanation in description.

Support for weather_disruption allows this normalized reason to be returned when an upstream provider supplies reliable evidence. It does not imply that JDL currently provides a mapped weather event. Weather must not be inferred from the shipment location or local forecast.

A later normal delivery has status: "delivered" and sub_status: null. Earlier exception details remain on their original checkpoints and must not be carried forward to the delivery checkpoint.

Recommended client handling

Evaluate the event timeline using local_time; checkpoints are returned newest first. Do not select the most severe status anywhere in the history as the current shipment state. If newer events are ambiguous, review their descriptions or reconcile the tracking data instead of assuming an outcome.
Treat delivered as the definitive successful-delivery status. A later normal delivery remains delivered even if an earlier checkpoint reported a failed attempt or an exception.
Treat delivered_with_exception as a delivered outcome that requires review; do not combine it with normal delivered reporting.
Do not treat delivery_attempt_failed as a final return. It may be followed by another delivery event.
Treat disposed as a distinct terminal outcome, not as a generic exception.
Do not infer return-to-origin or cancellation from exception alone. Use description and subsequent checkpoints to determine the shipment outcome.
When status is unknown, display description and continue processing the remaining checkpoints.

Temporary delivery issue followed by successful delivery

The following illustrative timeline uses Hong Kong local time (UTC+08:00). It demonstrates normalized status and sub-status semantics. Dates use YYYY-MM-DD to avoid ambiguity.

Event time (Hong Kong)	Event	Checkpoint status	Sub-status
2026-10-02 20:06	Out for delivery.	`out_for_delivery`	`null`
2026-10-02 20:24	The courier could not contact the recipient; another delivery was planned.	`delivery_attempt_failed`	`recipient_unavailable`
2026-10-03 13:10	Out for delivery again.	`out_for_delivery`	`null`
2026-10-03 13:30	The carrier confirmed normal delivery.	`delivered`	`null`

After the final event, the delivery outcome is delivered. The unsuccessful attempt remains a historical event; it does not mean that the shipment is still in exception or was delivered with exception. A planned redelivery time is not confirmation that delivery occurred; use the actual subsequent checkpoint.

The corresponding illustrative checkpoints fragment is returned newest first, with timestamps converted to UTC. Descriptions are simplified and contain no personal contact details.

json

{
  "checkpoints": [
    {
      "local_time": "2026-10-03T05:30:00Z",
      "status": "delivered",
      "sub_status": null,
      "details": "Kwun Tong, Hong Kong",
      "description": "Delivery confirmed by the carrier."
    },
    {
      "local_time": "2026-10-03T05:10:00Z",
      "status": "out_for_delivery",
      "sub_status": null,
      "details": "Kwun Tong, Hong Kong",
      "description": "Out for delivery again."
    },
    {
      "local_time": "2026-10-02T12:24:00Z",
      "status": "delivery_attempt_failed",
      "sub_status": "recipient_unavailable",
      "details": "Kwun Tong, Hong Kong",
      "description": "Unable to contact the recipient; another delivery was planned."
    },
    {
      "local_time": "2026-10-02T12:06:00Z",
      "status": "out_for_delivery",
      "sub_status": null,
      "details": "Kwun Tong, Hong Kong",
      "description": "Out for delivery."
    }
  ]
}

Response

json

{
  "code": 200,
  "message": "OK – The request was successful.",
  "data": {
    "tracking_courier": "ups",
    "tracking_number": "92612902******9",
    "outbound_time": null,
    "delivered_time": "2026-09-04T09:06:00Z",
    "checkpoints": [
      {
        "local_time": "2026-09-04T09:06:00Z",
        "status": "delivered",
        "sub_status": null,
        "details": "Cincinnati,US",
        "description": "Delivered"
      },
      {
        "local_time": "2026-09-03T22:10:00Z",
        "status": "out_for_delivery",
        "sub_status": null,
        "details": "Cincinnati,US",
        "description": "Out for Delivery"
      },
      {
        "local_time": "2026-09-03T21:22:00Z",
        "status": "in_transit",
        "sub_status": null,
        "details": "Cincinnati,US",
        "description": "Arrived at Post Office"
      },
      {
        "local_time": "2026-09-03T20:07:00Z",
        "status": "in_transit",
        "sub_status": null,
        "details": "Cincinnati,US",
        "description": "Accepted at USPS Destination Sort Facility"
      },
      {
        "local_time": "2026-08-29T04:03:00Z",
        "status": "in_transit",
        "sub_status": null,
        "details": "Urbancrest,US",
        "description": "Departure Scan: Enroute to USPS"
      },
      {
        "local_time": "2026-08-28T17:26:00Z",
        "status": "in_transit",
        "sub_status": null,
        "details": "Urbancrest,US",
        "description": "Arrived at UPS Facility"
      },
      {
        "local_time": "2026-08-27T20:07:00Z",
        "status": "in_transit",
        "sub_status": null,
        "details": "Orlando,US",
        "description": "Departed UPS Facility"
      },
      {
        "local_time": "2026-08-27T14:38:00Z",
        "status": "in_transit",
        "sub_status": null,
        "details": "Orlando,US",
        "description": "Package processed"
      },
      {
        "local_time": "2026-08-26T12:05:00Z",
        "status": "information_received",
        "sub_status": null,
        "details": null,
        "description": "Shipment information received by ZhenHub."
      }
    ]
  }
}

Order Not Found

HTTP status: 404 Not Found

json

{
  "code": 404,
  "message": "Order not found.",
  "data": null
}

Before Carrier Allocation

When the label order exists but ZhenHub has not yet allocated a carrier, the request succeeds. tracking_courier and tracking_number are returned as explicit null values; they are not empty strings and are not omitted.

json

{
  "code": 200,
  "message": "OK – The request was successful.",
  "data": {
    "tracking_courier": null,
    "tracking_number": null,
    "outbound_time": null,
    "delivered_time": null,
    "checkpoints": [
      {
        "local_time": "2026-08-26T01:09:01Z",
        "status": "information_received",
        "sub_status": null,
        "details": null,
        "description": "Shipment information received by ZhenHub."
      }
    ]
  }
}

Notes

The response returns a single tracking object.
checkpoints[].local_time is normalized to UTC and uses ISO 8601 format (for example, 2026-09-04T09:06:00Z).
information_received indicates that ZhenHub has received and registered the shipment information. It does not indicate that the carrier has physically collected the shipment.
Before carrier allocation, tracking_courier and tracking_number are explicit null values. Clients should continue polling the same Label Tracking endpoint.
outbound_time is optional and may remain null for carriers such as JDL. Do not universally interpret it as the dispatch timestamp.
delivered_time may be null if the shipment has not been delivered.
checkpoints contains the complete shipment tracking history returned by the carrier, sorted in reverse chronological order (latest event first).

GET /2026-05/cloud/label/tracking/{id} ​

Parameters required to be sent ​

Response Parameters ​

Checkpoint status reference ​

Checkpoint sub-status reference ​

Recommended client handling ​

Temporary delivery issue followed by successful delivery ​

Response ​

Order Not Found ​

Before Carrier Allocation ​

Notes ​

`GET` /2026-05/cloud/label/tracking/{id}

Parameters required to be sent

Response Parameters

Checkpoint status reference

Checkpoint sub-status reference

Recommended client handling

Temporary delivery issue followed by successful delivery

Response

Order Not Found

Before Carrier Allocation

Notes