API REFERENCE · TRACKING

International shipment tracking

Look up carrier scan events with a logistics tracking number, warehouse order number, or client order number.

Track a shipment

Call the XMPacket server endpoint. Your HioBuy API key stays on the server and is never sent to the browser.

GET /api/tracking?sn=YOUR_TRACKING_NUMBER

Query parameters

NameTypeRequiredDescription

snstringYesLogistics tracking number, warehouse order number, or client order number. Maximum 200 characters.

The tracking number is forwarded unchanged to HioBuy. URL-encode it when constructing the query string.

Successful response

HTTP 200 returns the normalized shipment record.

{
  "data": {
    "id": "shipment_id",
    "order_sn": "warehouse_order_number",
    "tracking_number": "YOUR_TRACKING_NUMBER",
    "shipping_channel": "Carrier name",
    "status": "IN_TRANSIT",
    "status_label": "In Transit",
    "timeline": [
      {
        "time": "2026-11-04T10:30:00Z",
        "status": "IN_TRANSIT",
        "label": "Departed facility",
        "description": "Shipment is moving",
        "location": "London, United Kingdom",
        "station_name": null
      }
    ],
    "request_id": "request_id",
    "source": "live"
  },
  "request_id": "request_id"
}

Errors

HTTPCodeMeaning

400INVALID_TRACKING_NUMBERMissing or longer than 200 characters.

401TRACKING_AUTH_ERRORServer credential rejected upstream.

403TRACKING_PERMISSION_ERRORAPI key lacks tracking:read permission.

404TRACKING_NOT_FOUNDNo matching tracking events.

503TRACKING_NOT_CONFIGUREDServer HIOBUY_API_KEY is not configured.

502TRACKING_UPSTREAM_ERRORUpstream request failed.

cURL example

curl "https://YOUR_DOMAIN/api/tracking?sn=YOUR_TRACKING_NUMBER"

JavaScript example

const response = await fetch(
  "/api/tracking?sn=" + encodeURIComponent(trackingNumber)
);
const result = await response.json();

SecurityNever expose HIOBUY_API_KEY in client code. Configure it as a server-only environment variable.