Shipment Status Query API Development Document

package journey

The API will automatically determine which stage the package is in based on the order number, and return the current status, complete timeline, and (if it has entered Taiwan Customs) the GC329 five-stage customs clearance progress.

Base URL

Authentication header (choose one)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// 或
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Please call it from the server side and do not put the key in front-end JavaScript. The rate limit is in key units, and the response header X-RateLimit-Remaining will report the remaining limit; if the limit is exceeded, HTTP 429 will be returned.

GETPOST /api/v1/shipment/track

Check the shipment status of a single package based on the tracking number. Both GET (query string) and POST (JSON / form) are acceptable.

Request parameters

parameter	Type	Required	illustrate
tracking_number	string	Required	Package tracking number (4–64 characters, alphanumeric and - _). China Express Tracking Number / Customer Tracking Number / Shipping Tracking Number are all acceptable.

Request example (GET)

curl "https://0523.tw/api/v1/shipment/track?tracking_number=SF1234567890123" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response 200 (Example already in warehouse/in transit)

{
  "success": true,
  "cached": false,
  "tracking_number": "SF1234567890123",
  "data": {
    "tracking_number": "SF1234567890123",
    "customer_order_no": "LK260601001",
    "carrier_tracking_no": "SF1234567890123",
    "logistics": "順豐速運",
    "status_code": 2,
    "status": "已入倉",
    "description": "包裹已進入深圳集運倉,等待集運打包",
    "is_delivered": false,
    "is_final": false,
    "last_event_time": "2026-06-01 12:30:00",
    "updated_at": "2026-06-01 12:31:05",
    "timeline": [
      { "name": "已攬收", "completed": true,  "time": "2026-05-30 09:00:00" },
      { "name": "已入倉 (深圳集運倉)", "completed": true,  "time": "2026-06-01 12:30:00" },
      { "name": "集運打包/台灣運送", "completed": false, "time": null },
      { "name": "已簽收", "completed": false, "time": null }
    ],
    "customs_stages": null,
    "events": null
  }
}

Response 404 (no order number found)

{
  "success": false,
  "error": "not_found",
  "message": "查無此單號。請確認單號正確,或包裹尚未進入集運系統。",
  "tracking_number": "SF1234567890123"
}

field	Type	illustrate
status	string	Current status (human readable) , such as forecasted / warehoused / in transit / dispatched to Taiwan / signed for receipt. It is recommended to display this string directly.
status_code	number	Status code (depends on source, see next section). It is recommended to use status, is_delivered, is_final to drive the UI.
is_delivered	bool	Has it been signed for?
is_final	bool	Whether it is final (signed/returned/cancelled/undeliverable). True to stop polling.
logistics	string	Logistics provider (China Express or Taiwan terminal delivery).
description	string	Latest event description.
last_event_time	datetime	The time of the latest logistics event.
timeline	array	Stage timeline, each item contains name / completed / time / description.
customs_stages	object|null	Taiwan Customs GC329 Customs clearance progress (null if customs clearance has not yet been completed). See next section.
events	array|null	Original logistics event history (provided during terminal delivery tracking).

Main stage of consolidation (timeline)

stage	significance
Forecasted (not entered into warehouse)	The customer has predicted the order number, but the package has not yet arrived at the Shenzhen Consolidation Warehouse.
Already warehoused (Shenzhen Container Warehouse)	Shenzhen Consolidation Warehouse has received the package.
Consolidation and packaging/Taiwan delivery	Packed and shipped, shipped by sea/air to Taiwan.
In transit/delivering to Taiwan	Customs clearance and final delivery after arrival in Taiwan.
Signed for	The recipient has signed for delivery (is_delivered = true).

Customs clearance stages (customs_stages,GC329)

After the package enters Taiwan Customs, customs_stages will bring out the five-stage progress and overall percentage:

{
  "hbl": "691MK539819",
  "trans_type_name": "海運",
  "current_stage_name": "海關放行",
  "progress_percent": 80,
  "is_completed": false,
  "stages": [
    { "code": "XX", "name": "船(機)抵達",   "done": true },
    { "code": "E1", "name": "連線收單建檔", "done": true },
    { "code": "D1", "name": "計稅",        "done": true },
    { "code": "RL", "name": "海關放行",     "done": true },
    { "code": "OW", "name": "出倉",        "done": false }
  ],
  "source": "關港貿單一窗口 GC329"
}

HTTP	error	illustrate
401	missing_api_key / invalid_api_key	No/invalid API Key.
403	insufficient_scope	The key has not been granted the shipment:read permission.
404	not_found	This tracking number is not found, or the package has not yet entered the consolidation system.
422	validation_failed	tracking_number is missing or does not match the format.
429	rate_limit_exceeded	Exceeding the request limit per minute, see Retry-After.

• Polling frequency : It is recommended to check the same order number every 15-30 minutes; the result is cached on this server for 5 minutes (cached: true means hit).
• stops polling : Stop polling when is_final = true (signed/returned/cancelled).
• status driver : Display with status string, use is_delivered / is_final to judge the process to avoid hard coding status_code (different source code definitions are different).
• No order number :404 Most likely means that the package has not yet entered the consolidation system (the customer has just placed an order but has not sent it), and you can try again later.

technical support: howyunqisoftware@gmail.com

API version: v1 (stable).

Change history: 2026-06-01 — Shipment status query API v1 is online.