curl --request POST \
  --url https://api.zangsho.com/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "order_no": "ORD-20260109-001",
  "amount": "990.00",
  "status": "paid",
  "customer_email": "customer@example.com",
  "customer_name": "王小明",
  "currency": "TWD",
  "payment_method": "credit_card",
  "billing_cycle": "monthly",
  "paid_at": "2026-01-09T08:00:00Z"
}
'

{
  "data": {
    "id": 123,
    "order_no": "<string>",
    "amount": "<string>",
    "currency": "TWD",
    "billing_cycle": "<string>",
    "paid_at": "2023-11-07T05:31:56Z",
    "refunded_at": "2023-11-07T05:31:56Z",
    "failed_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "customer_email": "<string>",
    "customer_name": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

{
  "message": "Unauthenticated."
}

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required.",
      "The email must be a valid email address."
    ]
  }
}

訂單 Orders

建立訂單

建立單一訂單。

Webhook 觸發

建立成功時觸發 order.created 事件
若 status 為 paid，同時觸發 order.paid 事件

時間戳記自動填入

若建立訂單時指定了 status 但未提供對應的時間欄位，系統會自動填入當前時間：

status: paid → 自動填入 paid_at
status: refunded → 自動填入 refunded_at
status: failed → 自動填入 failed_at

如果你已提供時間欄位（例如匯入歷史資料時），系統不會覆蓋你提供的值。

冪等處理

可透過 X-Idempotency-Key header 實現冪等，重複請求會回傳相同結果。

POST

orders

curl --request POST \
  --url https://api.zangsho.com/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "order_no": "ORD-20260109-001",
  "amount": "990.00",
  "status": "paid",
  "customer_email": "customer@example.com",
  "customer_name": "王小明",
  "currency": "TWD",
  "payment_method": "credit_card",
  "billing_cycle": "monthly",
  "paid_at": "2026-01-09T08:00:00Z"
}
'

{
  "data": {
    "id": 123,
    "order_no": "<string>",
    "amount": "<string>",
    "currency": "TWD",
    "billing_cycle": "<string>",
    "paid_at": "2023-11-07T05:31:56Z",
    "refunded_at": "2023-11-07T05:31:56Z",
    "failed_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "customer_email": "<string>",
    "customer_name": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

{
  "message": "Unauthenticated."
}

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required.",
      "The email must be a valid email address."
    ]
  }
}

Authorizations

Authorization

string

header

required

使用 Laravel Sanctum Token 進行認證。

Token 可在商家後台的「API 設定」頁面取得。

Headers

X-Idempotency-Key

string

冪等鍵（24 小時內有效）

Body

application/json

order_no

string

required

訂單編號（商家內唯一）

Example:

"ORD-20260109-001"

amount

string

required

訂單金額

Example:

"990.00"

customer_email

string<email>

required

客戶 Email（不存在會自動建立客戶）

status

enum<string>

default:pending

訂單狀態

Available options:

pending,

paid,

failed,

refunded,

cancelled

customer_name

string

客戶姓名（建立新客戶時使用）

currency

string

default:TWD

幣別，使用 ISO 4217 貨幣代碼。預設為 TWD（新台幣）。

常見幣別：

代碼	說明
`TWD`	新台幣
`USD`	美元
`JPY`	日圓
`HKD`	港幣
`SGD`	新加坡幣
`CNY`	人民幣
`KRW`	韓元
`MYR`	馬來西亞令吉
`THB`	泰銖
`EUR`	歐元
`GBP`	英鎊

Example:

"TWD"

payment_method

enum<string>

付款方式。支援以下選項：

值	說明
`credit_card`	信用卡
`atm`	ATM 轉帳
`cvs`	超商繳費（代碼繳費）
`line_pay`	LINE Pay
`jkopay`	街口支付
`apple_pay`	Apple Pay

Available options:

credit_card,

atm,

cvs,

line_pay,

jkopay,

apple_pay

Example:

"credit_card"

billing_cycle

enum<string>

訂閱週期（影響 MRR 計算）

Available options:

monthly,

quarterly,

semi-annual,

yearly,

one-time

paid_at

string<date-time>

付款時間（若未提供且 status 為 paid，系統自動填入當前時間）

refunded_at

string<date-time>

退款時間（若未提供且 status 為 refunded，系統自動填入當前時間）

failed_at

string<date-time>

付款失敗時間（若未提供且 status 為 failed，系統自動填入當前時間）

metadata

object

自訂欄位

Response

訂單建立成功

data

object

Show child attributes

批次匯入客戶列出訂單