> ## 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.

# 訂閱

> 了解帳獸中訂閱的狀態管理、事件追蹤與來源優先順序

## 什麼是訂閱

訂閱（Subscription）代表客戶與你的商家之間的持續付費關係。在帳獸中，訂閱是計算 MRR（月經常性收入）、Churn Rate（流失率）等 SaaS 指標的核心資料。

<Info>
  每位客戶在每個商家下**只能有一個訂閱**。這代表帳獸追蹤的是客戶整體的訂閱狀態，而非個別方案的訂閱。
</Info>

## 訂閱狀態

| 狀態          | 說明    | 計入活躍客戶 | 計入 MRR |
| ----------- | ----- | :----: | :----: |
| `active`    | 活躍訂閱中 |    ✅   |    ✅   |
| `cancelled` | 已取消   |    ❌   |    ❌   |
| `paused`    | 已暫停   |    ❌   |    ❌   |

<Warning>
  `paused`（已暫停）的訂閱**不計入** Active Customers 和 MRR 統計。如果你希望保留客戶的訂閱紀錄但暫時停止計費，可以使用暫停功能。
</Warning>

### 狀態轉換

```
active → cancelled    （取消訂閱）
active → paused       （暫停訂閱）
cancelled → active    （重新啟用）
paused → active       （恢復訂閱）
```

## 訂閱屬性

| 屬性                     | 類型       | 說明                 |
| ---------------------- | -------- | ------------------ |
| `customer_id`          | integer  | 所屬客戶               |
| `status`               | string   | 訂閱狀態               |
| `plan_name`            | string   | 方案名稱（如 `Pro Plan`） |
| `mrr`                  | string   | 當前月經常性收入（已正規化）     |
| `billing_cycle`        | string   | 訂閱週期               |
| `source`               | string   | 資料來源               |
| `started_at`           | datetime | 首次訂閱時間             |
| `current_period_start` | datetime | 當前週期開始時間           |
| `cancelled_at`         | datetime | 取消時間               |

## 訂閱來源

帳獸支援三種訂閱資料來源：

| 來源         | 說明               |
| ---------- | ---------------- |
| `api`      | 商家透過 API 主動建立或更新 |
| `inferred` | 系統從訂單金額變化自動推導    |
| `manual`   | 在後台手動操作          |

### 來源覆蓋優先順序

不同來源之間有嚴格的覆蓋規則，確保資料的準確性：

```
manual > api > inferred
```

| 新來源 → 舊來源               | 是否允許覆蓋 |
| ----------------------- | :----: |
| `manual` → 任何來源         |    ✅   |
| `api` → `inferred`      |    ✅   |
| `api` → `api`           |    ✅   |
| `inferred` → `inferred` |    ✅   |
| `inferred` → `api`      |    ❌   |

<Info>
  `inferred`（系統推導）不可覆蓋 `api`（商家推送）的資料。這是為了保護商家透過 API 主動設定的精確訂閱資訊。
</Info>

## 訂閱有效期

訂閱的有效期基於 `current_period_start` 加上訂閱週期的月數：

| 訂閱週期          | 有效期月數 |
| ------------- | ----- |
| `monthly`     | 1 個月  |
| `quarterly`   | 3 個月  |
| `semi-annual` | 6 個月  |
| `yearly`      | 12 個月 |

只有在有效期內且狀態為 `active` 的訂閱，才會被計入 Active Customers 和 MRR。

## 重新啟用（Reactivation）

當已取消或已暫停的訂閱重新啟用時：

* `started_at` **保持不變**：保留客戶首次訂閱的時間記錄
* `current_period_start` **更新為新的起始時間**
* `cancelled_at` **清除為空**
* `status` **更新為 `active`**

<Tip>
  保留 `started_at` 可以讓你追蹤客戶最初是何時開始訂閱的，即使中間經歷了取消和重新啟用。
</Tip>

## 訂閱事件

訂閱事件（Subscription Event）記錄了訂閱狀態的每次變更，支援時間軸顯示與升降級分析。

### 事件類型

| 事件類型          | 說明       |
| ------------- | -------- |
| `created`     | 首次訂閱     |
| `upgrade`     | 升級（金額增加） |
| `downgrade`   | 降級（金額減少） |
| `cancel`      | 取消訂閱     |
| `reactivated` | 重新啟用     |

### 事件來源

| 來源         | 說明                |
| ---------- | ----------------- |
| `api`      | 商家透過訂閱事件 API 主動推送 |
| `inferred` | 系統從訂單金額變化自動推導     |

<Note>
  如果你的系統能精確掌握訂閱方案的變更資訊（如舊方案名稱、新方案名稱），建議使用 [訂閱事件 API](/api-reference/introduction) 主動推送，可以獲得更精確的分析結果。
</Note>

### 事件屬性

每個訂閱事件包含以下資訊：

| 屬性              | 說明         |
| --------------- | ---------- |
| `event_type`    | 事件類型       |
| `old_amount`    | 變更前金額（MRR） |
| `new_amount`    | 變更後金額（MRR） |
| `amount_change` | 金額變化量      |
| `old_plan`      | 變更前方案名稱    |
| `new_plan`      | 變更後方案名稱    |
| `occurred_at`   | 事件發生時間     |

## 下一步

<CardGroup cols={2}>
  <Card title="SaaS 指標" icon="chart-pie" href="/concepts/saas-metrics">
    了解訂閱如何驅動 20 項 SaaS 核心指標。
  </Card>

  <Card title="客戶洞察" icon="users" href="/concepts/customers">
    了解客戶的 LTV 計算與訂閱事件時間軸。
  </Card>
</CardGroup>