什麼是訂閱
訂閱（Subscription）代表客戶與你的商家之間的持續付費關係。在帳獸中，訂閱是計算 MRR（月經常性收入）、Churn Rate（流失率）等 SaaS 指標的核心資料。
每位客戶在每個商家下只能有一個訂閱。這代表帳獸追蹤的是客戶整體的訂閱狀態，而非個別方案的訂閱。
訂閱狀態
| 狀態 | 說明 | 計入活躍客戶 | 計入 MRR |
|---|
active | 活躍訂閱中 | ✅ | ✅ |
cancelled | 已取消 | ❌ | ❌ |
paused | 已暫停 | ❌ | ❌ |
paused（已暫停）的訂閱不計入 Active Customers 和 MRR 統計。如果你希望保留客戶的訂閱紀錄但暫時停止計費，可以使用暫停功能。
狀態轉換
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 | ✅ |
api → api | ✅ |
inferred → inferred | ✅ |
inferred → api | ❌ |
inferred（系統推導）不可覆蓋 api（商家推送）的資料。這是為了保護商家透過 API 主動設定的精確訂閱資訊。
訂閱有效期
訂閱的有效期基於 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
保留 started_at 可以讓你追蹤客戶最初是何時開始訂閱的，即使中間經歷了取消和重新啟用。
訂閱事件
訂閱事件（Subscription Event）記錄了訂閱狀態的每次變更，支援時間軸顯示與升降級分析。
事件類型
| 事件類型 | 說明 |
|---|
created | 首次訂閱 |
upgrade | 升級（金額增加） |
downgrade | 降級（金額減少） |
cancel | 取消訂閱 |
reactivated | 重新啟用 |
事件來源
| 來源 | 說明 |
|---|
api | 商家透過訂閱事件 API 主動推送 |
inferred | 系統從訂單金額變化自動推導 |
如果你的系統能精確掌握訂閱方案的變更資訊（如舊方案名稱、新方案名稱），建議使用 訂閱事件 API 主動推送，可以獲得更精確的分析結果。 事件屬性
每個訂閱事件包含以下資訊：
| 屬性 | 說明 |
|---|
event_type | 事件類型 |
old_amount | 變更前金額（MRR） |
new_amount | 變更後金額（MRR） |
amount_change | 金額變化量 |
old_plan | 變更前方案名稱 |
new_plan | 變更後方案名稱 |
occurred_at | 事件發生時間 |
下一步
