---
title: "訂閱生命週期與計費"
description: "本頁說明訂閱在其生命週期中如何流轉、計費週期和續訂如何計算，以及失敗的付款如何處理。"
source: "https://docs.tokenz.one/zh-TW/v2/subscriptions/lifecycle"
api_version: "v2"
locale: "zh-TW"
version_status: "current"
docs_stage: "prod"
---

# 訂閱生命週期與計費

本頁說明訂閱在其生命週期中如何流轉、計費週期和續訂如何計算，以及失敗的付款如何處理。

## 狀態

| 狀態 | 意義 |
| --- | --- |
| `created` | 訂閱已建立，但消費者尚未完成授權。 |
| `trialing` | 消費者正處於試用期。尚未發生任何扣款。 |
| `active` | 訂閱正常計費。每個計費週期結束時會自動建立新訂單並扣款。 |
| `unpaid` | 目前計費週期的訂單未能成功付款。訂閱正處於催收狀態，之後將恢復為 `active` 或終止為 `expired`。 |
| `canceled` | 由商戶代表消費者取消。終止狀態——不會再產生扣款。 |
| `expired` | 因始終無法收款（初始扣款失敗，或催收已耗盡）而非自願終止。終止狀態——不會再產生扣款。 |

`canceled` 和 `expired` 都是終止狀態，但意義不同：`canceled` 是商戶代表消費者主動取消，而 `expired` 反映的是付款失敗。在您自己的流失分析中應區分這兩者。

## 計費週期

每個處於活躍狀態的訂閱都有一個 `currentBillingPeriodEnd` 時間戳記，處於試用狀態的訂閱還會有一個 `trialEnd` 時間戳記。

- **間隔（Interval）**：一個包含 `unit`（`WEEK`、`MONTH` 或 `YEAR`）和 `count`（兩次續訂之間的單位數）的物件。按月和按年的週期會順延至與訂閱的計費錨點（首次成功扣款）相同的日期；若錨點當天在目標月份中不存在（例如錨點為 31 號，而目標月較短），則順延至該月最後一天（30 號或 28/29 號）。
- **續訂（Renewal）**：由 Tokenz 在目前計費週期結束時自動管理。

```mermaid
sequenceDiagram;
autonumber;
participant T as Tokenz;
participant PSP as 卡組織 / PSP;
participant W as 商戶 webhook 處理程式;
T->>T: 為該計費週期建立續訂訂單;
T->>PSP: 向已儲存的卡扣款;
alt 支付成功
PSP-->>T: 已授權;
T->>T: 推進計費週期，訂閱保持 active;
T->>W: webhook: subscription.renewed;
else 支付失敗
PSP-->>T: 已拒絕;
T->>T: 將訂閱標記為 unpaid，開始催收;
T->>W: webhook: subscription.unpaid;
end
```

## 試用期

如果在建立訂閱時設定了 `trialPeriodDays`（1–365），結帳時不會建立初始訂單。而是按以下流程進行：

1. 消費者透過提供卡片資訊開始試用。Tokenz 會在支付網路中登記支付同意——參見[支付方式與授權](https://docs.tokenz.one/zh-TW/v2/subscriptions/payment-methods)。
2. 訂閱進入 `trialing` 狀態，並發送 `subscription.trial_started` webhook。
3. 當試用達到 `trialEnd` 時，系統會建立訂單並使用已儲存的卡進行扣款。成功後，訂閱變為 `active`，並發送 `subscription.activated` webhook。

如果未設定試用期，初始訂單會在結帳時建立並扣款，授權成功後訂閱立即變為 `active`。

## 催收（付款失敗復原）

每個訂閱在建立時都會設定一個催收策略，用於控制計畫扣款失敗時的處理方式：

- **`RETRY`**（預設）：未付款的訂單會在其到期窗口（`dunningExpireAfterHours`，預設 24 小時）耗盡之前，最多重試 `dunningMaxAttempts` 次（預設 3 次），並按一定間隔分散進行。消費者還會收到一封包含復原結帳連結的郵件，以便在需要時更新卡片。如果某次重試成功，訂閱會恢復為 `active`。如果所有重試均失敗且訂單過期，訂閱將變為 `expired`。
- **`CANCEL_IMMEDIATELY`**：首次扣款失敗會立即使訂閱失效——沒有重試窗口。

| 欄位 | 說明 |
| --- | --- |
| `dunningMode` | `RETRY` 或 `CANCEL_IMMEDIATELY`。預設值為 `RETRY`。 |
| `dunningMaxAttempts` | 當 `dunningMode` 為 `RETRY` 時的最大重試次數。1–10，預設 3。 |
| `dunningExpireAfterHours` | 當 `dunningMode` 為 `RETRY` 時，未付款訂單過期前的小時數。1–168，預設 24。 |

> **注意：** 從 `unpaid` 復原到 `active` 不會移動原有的計費週期——下一次續訂仍按原始錨點日期排程，而不是按復原日期排程。

## 取消

只要訂閱處於 `trialing`、`active` 或 `unpaid` 狀態，商戶即可代表消費者取消訂閱。取消操作會：

- 設定 `canceledAt` 並停止產生後續的續訂訂單
- 取消該訂閱任何處理中的訂單（例如仍在等待付款的訂單）
- 發送 `subscription.canceled` webhook

取消是最終操作——目前沒有辦法恢復已取消的訂閱。消費者需要重新開始一個新的訂閱。

## 續訂提醒

在部分地區，法規要求在特定扣款前發出通知（例如試用轉正式扣款之前，或年度續訂之前）；在有此要求時，Tokenz 會自動發送這些通知。