訂單、退款和收款鏈接都支持 metadata：一組你自己定義的鍵值對，隨對象一起存儲、一起返回、一起出現在 Webhook 裏。
用它把 KukoPay 的對象和你自己系統裏的記錄關聯起來，而不是把多個 id 編碼進 out_trade_no 再解析出來——out_trade_no 是冪等鍵，不該兼任這個職責。
寫入
curl -X POST "https://api.kukopay.com/v1/orders" \
-H "X-Api-Key: kuko_live_你的密鑰" \
-H "Content-Type: application/json" \
-d '{
"out_trade_no": "ORD_20260921_0001",
"amount": 2990,
"metadata": {
"customer_id": "cus_42",
"order_source": "shopify",
"sales_rep": "alice"
}
}'限制
| 項目 | 限制 |
|---|---|
| 鍵數量 | 最多 50 個 |
| 鍵長度 | 1 ~ 40 字符 |
| 值長度 | 不超過 500 字符 |
| 值類型 | 必須是字符串 |
只允許字符串是有意的限制。允許嵌套結構，metadata 就會變成一份我們必須永遠兼容的隱式 schema——需要結構化數據時，請在自己的系統裏存，這裏只放一個指向它的 id。
按 metadata 查詢訂單
curl -G "https://api.kukopay.com/v1/orders" \
-H "X-Api-Key: kuko_live_你的密鑰" \
-d "metadata[customer_id]=cus_42"可以傳多個，含義是"同時滿足"。
創建後修改
POST /v1/orders/{trade_no}
POST /v1/refunds/{refund_no}
POST /v1/payment_links/{link_id}這些接口目前只支持更新 metadata——金額、幣種和環境是已經告知上游渠道的事實，允許在這裏改會讓平台記錄與真實資金脱節。
更新是增量合併，不是整體替換：
# 只寫入 shipped_at，其它鍵保持不變
curl -X POST "https://api.kukopay.com/v1/orders/TRD_9F3A2C7E" \
-H "X-Api-Key: kuko_live_你的密鑰" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "shipped_at": "2026-09-22" } }'
# 值傳 null 刪除單個鍵
curl -X POST "https://api.kukopay.com/v1/orders/TRD_9F3A2C7E" \
-H "X-Api-Key: kuko_live_你的密鑰" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "sales_rep": null } }'整個 metadata 字段傳 null 表示清空。
合併而不是替換，是為了讓只認識自己那個鍵的客戶端不會把別的系統寫入的鍵洗掉。