什麼是客戶
客戶（Customer）是帳獸中的基礎資料單位，代表向你購買商品或服務的消費者。所有的營收分析、LTV（客戶終身價值）計算都以客戶為中心展開。
客戶來源
客戶資料可以透過以下方式進入帳獸：
- API 建立：透過 建立客戶 API 主動建立
- 訂單自動提取：當你建立訂單時，系統會自動根據
customer_id 關聯客戶
- 批次匯入：使用 批次匯入 API 一次匯入大量客戶資料
- 金流通知：透過藍新或綠界金流整合，付款成功時自動建立客戶
客戶屬性
| 屬性 | 類型 | 必填 | 說明 |
|---|
email | string | ✅ | 客戶 Email，在同一商家內唯一 |
name | string | — | 客戶姓名 |
phone | string | — | 客戶電話 |
metadata | object | — | JSON 格式的擴充資料，可自由存放額外資訊 |
first_payment_at | datetime | — | 首次成功付款時間（系統自動記錄） |
last_payment_at | datetime | — | 最後成功付款時間（系統自動記錄） |
email 是客戶的唯一識別欄位。同一商家下，不能有兩位客戶使用相同的 Email。如果嘗試建立重複的 Email，API 會回傳 422 驗證錯誤。
metadata 欄位允許你存放任意 JSON 資料，適合記錄帳獸未提供的自訂欄位：
{
"metadata": {
"source": "website",
"campaign": "2026-q1",
"vip_level": "gold",
"company": "範例科技股份有限公司"
}
}
客戶關聯
每位客戶在帳獸中有以下關聯：
- 訂單（一對多）：一位客戶可以有多筆訂單
- 訂閱事件（一對多）：記錄客戶的訂閱變更歷史（升級、降級、取消等）
LTV 計算方式
LTV（客戶終身價值）是帳獸自動為每位客戶計算的重要指標：
LTV=所有已付款訂單總額−退款訂單總額
LTV 採用即時計算，不依賴快取。每當你查詢客戶資料時，系統會從該客戶的所有訂單中即時計算出最新的 LTV 數值。
計算範例
假設客戶王小明有以下訂單紀錄：
| 訂單編號 | 金額 | 狀態 |
|---|
| ORD-001 | NT$1,990 | paid |
| ORD-002 | NT$2,990 | paid |
| ORD-003 | NT$990 | refunded |
| ORD-004 | NT$500 | cancelled |
cancelled 和 pending 狀態的訂單不計入 LTV 計算，只有 paid 和 refunded 狀態會被納入。
多租戶隔離
帳獸採用多租戶架構，每位客戶隸屬於一個商家。不同商家之間的客戶資料完全隔離，你只能查看和操作屬於自己商家的客戶。
下一步
