`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)
`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.

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	A delivery attempt was unsuccessful. The carrier may attempt delivery again.
`delivered`	Delivered	The shipment has been successfully delivered.
`delivered_with_exception`	Delivered with exception	The shipment is recorded as delivered, but an abnormal condition was reported. Review `description` for details.
`exception`	Exception	The shipment has an exception, such as a return, customs issue, loss, or damage. Review `description` for the specific event.
`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.

Recommended client handling

Treat delivered as the definitive successful-delivery status.
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.

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",
        "details": "Cincinnati,US",
        "description": "Delivered"
      },
      {
        "local_time": "2026-09-03T22:10:00Z",
        "status": "out_for_delivery",
        "details": "Cincinnati,US",
        "description": "Out for Delivery"
      },
      {
        "local_time": "2026-09-03T21:22:00Z",
        "status": "in_transit",
        "details": "Cincinnati,US",
        "description": "Arrived at Post Office"
      },
      {
        "local_time": "2026-09-03T20:07:00Z",
        "status": "in_transit",
        "details": "Cincinnati,US",
        "description": "Accepted at USPS Destination Sort Facility"
      },
      {
        "local_time": "2026-08-29T04:03:00Z",
        "status": "in_transit",
        "details": "Urbancrest,US",
        "description": "Departure Scan: Enroute to USPS"
      },
      {
        "local_time": "2026-08-28T17:26:00Z",
        "status": "in_transit",
        "details": "Urbancrest,US",
        "description": "Arrived at UPS Facility"
      },
      {
        "local_time": "2026-08-27T20:07:00Z",
        "status": "in_transit",
        "details": "Orlando,US",
        "description": "Departed UPS Facility"
      },
      {
        "local_time": "2026-08-27T14:38:00Z",
        "status": "in_transit",
        "details": "Orlando,US",
        "description": "Package processed"
      },
      {
        "local_time": "2026-08-26T12:05:00Z",
        "status": "information_received",
        "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",
        "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 ​

Recommended client handling ​

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

Recommended client handling

Response

Order Not Found

Before Carrier Allocation

Notes