> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zangsho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 客戶

> 了解帳獸中的客戶資料模型、屬性與 LTV 計算方式

## 什麼是客戶

客戶（Customer）是帳獸中的基礎資料單位，代表向你購買商品或服務的消費者。所有的營收分析、LTV（客戶終身價值）計算都以客戶為中心展開。

## 客戶來源

客戶資料可以透過以下方式進入帳獸：

* **API 建立**：透過 [建立客戶 API](/api-reference/introduction) 主動建立
* **訂單自動提取**：當你建立訂單時，系統會自動根據 `customer_id` 關聯客戶
* **批次匯入**：使用 [批次匯入 API](/guides/data-import) 一次匯入大量客戶資料
* **金流通知**：透過藍新或綠界金流整合，付款成功時自動建立客戶

## 客戶屬性

| 屬性                 | 類型       | 必填 | 說明                     |
| ------------------ | -------- | -- | ---------------------- |
| `email`            | string   | ✅  | 客戶 Email，**在同一商家內唯一**  |
| `name`             | string   | —  | 客戶姓名                   |
| `phone`            | string   | —  | 客戶電話                   |
| `metadata`         | object   | —  | JSON 格式的擴充資料，可自由存放額外資訊 |
| `first_payment_at` | datetime | —  | 首次成功付款時間（系統自動記錄）       |
| `last_payment_at`  | datetime | —  | 最後成功付款時間（系統自動記錄）       |

<Info>
  `email` 是客戶的唯一識別欄位。同一商家下，不能有兩位客戶使用相同的 Email。如果嘗試建立重複的 Email，API 會回傳 422 驗證錯誤。
</Info>

## metadata 擴充資料

`metadata` 欄位允許你存放任意 JSON 資料，適合記錄帳獸未提供的自訂欄位：

```json theme={null}
{
  "metadata": {
    "source": "website",
    "campaign": "2026-q1",
    "vip_level": "gold",
    "company": "範例科技股份有限公司"
  }
}
```

## 客戶關聯

每位客戶在帳獸中有以下關聯：

* **訂單**（一對多）：一位客戶可以有多筆訂單
* **訂閱事件**（一對多）：記錄客戶的訂閱變更歷史（升級、降級、取消等）

## LTV 計算方式

LTV（客戶終身價值）是帳獸自動為每位客戶計算的重要指標：

$$
\text{LTV} = \text{所有已付款訂單總額} - \text{退款訂單總額}
$$

<Note>
  LTV 採用**即時計算**，不依賴快取。每當你查詢客戶資料時，系統會從該客戶的所有訂單中即時計算出最新的 LTV 數值。
</Note>

### 計算範例

假設客戶王小明有以下訂單紀錄：

| 訂單編號    | 金額        | 狀態        |
| ------- | --------- | --------- |
| ORD-001 | NT\$1,990 | paid      |
| ORD-002 | NT\$2,990 | paid      |
| ORD-003 | NT\$990   | refunded  |
| ORD-004 | NT\$500   | cancelled |

王小明的 LTV = NT$1,990 + NT$2,990 - NT$990 = **NT$3,990\*\*

<Tip>
  `cancelled` 和 `pending` 狀態的訂單不計入 LTV 計算，只有 `paid` 和 `refunded` 狀態會被納入。
</Tip>

## 多租戶隔離

帳獸採用多租戶架構，每位客戶隸屬於一個商家。不同商家之間的客戶資料完全隔離，你只能查看和操作屬於自己商家的客戶。

## 下一步

<CardGroup cols={2}>
  <Card title="訂單" icon="receipt" href="/concepts/orders">
    了解訂單的狀態流程與 MRR 計算關係。
  </Card>

  <Card title="建立客戶 API" icon="code" href="/api-reference/introduction">
    查看客戶相關的 API 端點文件。
  </Card>
</CardGroup>