International shipment tracking API

Track by any supported serial number

Use this endpoint when the HioBuy shipment ID is not known:

GET /v1/fulfillment/tracking?sn=9400111899223857654321
Authorization: Bearer <API_KEY>

The required sn may be a logistics number (logistics_sn), warehouse order number (order_sn), or developer-supplied external shipment number (client_order_sn). HioBuy forwards it unchanged and the warehouse identifies its type automatically. URL-encode sn when building the query string. The endpoint requires the tracking:read scope.

Keep API keys on your server. A public tracking page should call your backend, which then calls HioBuy; never embed the API key in browser code.

The ID-oriented endpoint below remains available when a HioBuy shipment ID or external_shipment_id is already known.

GET /v1/fulfillment/shipments/{shipment_id}/tracking — warehouse → overseas recipient.

Not domestic procurement trace (seller → warehouse).
Not package tracking (HioBuy warehouse inbound timeline).
Not shipment detail: that response holds tracking numbers (international_tracking, shipping_legs[], boxes[].tracking) and warehouse business timeline[] (created / packed / paid). This route returns carrier scan nodes using the same standardized timeline event shape.

Path {shipment_id} accepts either the HioBuy shipment id or the external_shipment_id supplied at create time. Numeric-only values are sent to the warehouse as shipment_id; any value containing a non-digit is sent as external_shipment_id. Prefix developer identifiers, for example shp_MY-INTL-ORDER-001, because numeric-only values are reserved for HioBuy internal IDs. Optional language is for display copy in sandbox.

Warehouse upstream: POST /api/gateway-worker/v1/shipments/track. Retired: POST /v1/fulfillment/shipments/logistics/trace.

Request

GET /v1/fulfillment/shipments/107/tracking?language=en
Authorization: Bearer <API_KEY>

Response

Detail-aligned subset: id, order_sn, shipping_channel, international_tracking, status, status_label, interception, timeline[].

interception is independent of the shipment lifecycle status. It is null when no interception has been requested; otherwise it contains the current interception request state.

Each timeline[] item contains required code, status, title, occurred_at, and details fields. Use code and status for program logic; title is localized display copy. Timestamps are timezone-aware ISO 8601, details is {} when empty, events are newest first, and code is never empty or null.

{
  "id": "118",
  "order_sn": "JIYUNRI1358",
  "shipping_channel": {
    "code": "CJ-SEA",
    "name": "E-commerce Sea - CJ"
  },
  "international_tracking": {
    "tracking_number": null,
    "carrier": null
  },
  "status": "PENDING",
  "status_label": "Pending",
  "interception": null,
  "timeline": [
    {
      "code": "SHIPMENT_CREATED",
      "status": "PENDING",
      "title": "Order created",
      "occurred_at": "2026-08-23T11:14:58Z",
      "details": {}
    }
  ],
  "request_id": "req_xxx"
}

Field reference: response models. Standard codes and interception semantics: Shipments · timeline contract.