# 試用期 (/features/payments/trials)





試用期 [#試用期]

試用期讓顧客免費體驗您的產品，到期後自動轉為正式訂閱扣款。這是降低購買門檻、提升轉換率的有效策略。

運作方式概覽 [#運作方式概覽]

1. 在產品設定中啟用試用期，設定試用天數
2. 顧客結帳時，系統以 **NT$2 驗證扣款**確認信用卡有效
3. 試用期間顧客免費使用，訂閱狀態為 `trialing`
4. 試用期到期，系統自動扣全額並轉為 `active` 正式訂閱

***

試用期狀態流程 [#試用期狀態流程]

<Mermaid
  chart="
flowchart TD
pending([pending]) -- NT$2 驗證成功 --> trialing([trialing])
trialing -- 試用到期，扣款成功 --> active([active])
trialing -- 試用到期，扣款失敗 --> past_due([past_due])
trialing -- 顧客主動取消 --> cancelled([cancelled])
trialing -- 排程取消到期 --> expired([expired])
past_due -- 重試扣款成功 --> active
past_due -- 所有重試失敗 --> expired
cancelled -- 期滿 --> expired
"
/>

***

信用卡驗證（NT$2 驗證扣款） [#信用卡驗證nt2-驗證扣款]

<Callout type="info">
  **為什麼收 NT$2 而非全額？**

  試用期間不收取產品費用，但需確認顧客的信用卡有效。系統會進行一筆 NT$2 的驗證扣款，成功後立即取消授權（不會實際請款），確保試用期結束時能順利扣款。
</Callout>

驗證流程 [#驗證流程]

1. 顧客在結帳頁面輸入信用卡資訊
2. 系統向金流發起 **NT$2 授權交易**
3. 授權成功後，系統綁定信用卡以供後續扣款使用
4. 系統立即**取消授權**，不會實際扣款
5. 訂閱狀態從 `pending` 轉為 `trialing`

<Callout type="info">
  **免綁卡兌換**：當使用 100% 折扣優惠碼搭配 `collectPaymentMethod: 'if_required'` 時，不會進行 NT$2 驗證，也不需要綁定信用卡。訂閱會直接建立並進入 `TRIAL`（若有試用期）或 `ACTIVE` 狀態。詳見[零元結帳](/guides/checkout/hosted-checkout#零元結帳免綁卡兌換)。
</Callout>

***

試用期間的重要日期 [#試用期間的重要日期]

試用期間，訂閱的日期欄位有特殊含義：

| 欄位                     | 試用期間的值            | 說明              |
| ---------------------- | ----------------- | --------------- |
| `trial_ends_at`        | 試用結束日期            | 試用期到期的確切時間      |
| `current_period_start` | 訂閱建立日期            | 試用開始時間          |
| `current_period_end`   | = `trial_ends_at` | 試用期間，週期結束等同試用到期 |
| `next_billing_date`    | = `trial_ends_at` | 下次扣款即為試用到期日     |

<Callout type="warn">
  **current\_period\_end 在試用期間的含義不同**

  一般訂閱的 `current_period_end` 代表一個完整計費週期的結束（如一個月後）。但在試用期間，`current_period_end` 等同 `trial_ends_at`，代表試用期到期日，**不是**完整計費週期。

  試用到期轉正式訂閱後，`current_period_end` 才會反映真正的計費週期。
</Callout>

***

結帳流程（含試用期） [#結帳流程含試用期]

<Mermaid
  chart="
sequenceDiagram
participant 顧客
participant 結帳頁面
participant Recur
participant 金流
participant Webhook

顧客->>結帳頁面: 進入結帳頁面
結帳頁面->>Recur: 建立 Checkout Session
Recur-->>Webhook: checkout.created
Note right of Webhook: 結帳 Session 建立

顧客->>結帳頁面: 填寫姓名、Email
結帳頁面->>Recur: 建立訂閱記錄
Recur-->>Webhook: subscription.created
Note right of Webhook: 訂閱建立 (pending)

顧客->>結帳頁面: 輸入信用卡並送出
結帳頁面->>Recur: 執行 NT$2 驗證
Recur->>金流: NT$2 授權交易
金流-->>Recur: 授權結果

alt 驗證成功
Recur->>金流: 取消授權（不實際扣款）
Recur-->>Webhook: order.paid
Note right of Webhook: NT$2 驗證訂單
Recur-->>Webhook: subscription.activated
Note right of Webhook: 訂閱啟用 (trialing)
else 驗證失敗
Recur-->>Webhook: order.payment_failed
end

Recur-->>Webhook: checkout.completed
Note right of Webhook: 結帳流程完成
"
/>

<Callout type="info">
  **與一般結帳的差異**

  * 一般結帳：扣全額 → 訂閱狀態為 `active`
  * 試用期結帳：NT$2 驗證 → 取消授權 → 訂閱狀態為 `trialing`
</Callout>

***

試用期轉正式訂閱（Trial Graduation） [#試用期轉正式訂閱trial-graduation]

試用期到期後，系統自動將訂閱從 `trialing` 轉為 `active` 並扣取全額。

<Mermaid
  chart="
sequenceDiagram
participant 排程任務
participant Recur
participant 金流
participant Webhook

排程任務->>Recur: 偵測 trialEndsAt <= now
Recur->>Recur: TRIAL → ACTIVE
Recur->>Recur: 建立 Invoice
Recur-->>Webhook: invoice.created
Note right of Webhook: 帳單建立 (pending)

Recur->>金流: 執行信用卡扣款（全額）
金流-->>Recur: 回傳結果

alt 扣款成功
Recur-->>Webhook: invoice.paid
Recur-->>Webhook: subscription.renewed
Note right of Webhook: 訂閱轉正式 (active)
else 扣款失敗
Recur-->>Webhook: invoice.payment_failed
Recur-->>Webhook: subscription.past_due
Note right of Webhook: 訂閱進入逾期狀態
end
"
/>

<Callout type="warn">
  **扣款失敗處理**

  試用期轉正式扣款失敗時，行為取決於產品的「付款寬限期」設定：

  * **寬限期啟用（預設）：** 訂閱進入 `past_due` 狀態，系統在 3 天寬限期內自動重試扣款（最多 3 次）。若所有重試都失敗，訂閱將被取消。
  * **寬限期關閉：** 訂閱立即取消（`canceled`），不會重試。

  詳見[催繳與寬限期](/features/automation/dunning)。
</Callout>

***

試用期間的操作 [#試用期間的操作]

方案切換 [#方案切換]

<Callout type="info">
  **試用期間切換方案不涉及差額計算**

  試用期間尚未付費，因此切換方案時不會計算差額。新方案的價格將在試用期結束時生效。試用到期日（`trial_ends_at`）不會因方案切換而改變。
</Callout>

取消訂閱 [#取消訂閱]

試用期間，顧客可以隨時取消訂閱：

* **立即取消**：訂閱立即變為 `cancelled`，不再扣款
* **週期結束取消**：訂閱在試用期到期時過期，不扣全額

***

延長試用（透過優惠碼） [#延長試用透過優惠碼]

透過「延長試用」類型的優惠碼，可以在產品原有試用期的基礎上額外增加試用天數。

**範例：** 產品設定 7 天試用 + 優惠碼延長 14 天 = 共 21 天試用

<Callout type="info">
  詳細設定方式請參考[時間加成 - 延長試用](/features/promotions/bonuses#延長試用)。
</Callout>

***

技術整合 [#技術整合]

Webhook 事件時序 [#webhook-事件時序]

以下是試用期訂閱從建立到轉正式的完整事件時序：

| 階段   | 事件                       | 訂閱狀態       | 說明            |
| ---- | ------------------------ | ---------- | ------------- |
| 結帳   | `checkout.created`       | -          | 結帳 Session 建立 |
| 結帳   | `subscription.created`   | `pending`  | 訂閱記錄建立        |
| 驗證   | `order.paid`             | `pending`  | NT$2 驗證成功     |
| 驗證   | `subscription.activated` | `trialing` | 訂閱進入試用        |
| 結帳   | `checkout.completed`     | `trialing` | 結帳流程完成        |
| 試用到期 | `invoice.created`        | `trialing` | 全額帳單建立        |
| 試用到期 | `invoice.paid`           | `active`   | 全額扣款成功        |
| 試用到期 | `subscription.renewed`   | `active`   | 訂閱轉正式         |

判斷訂閱是否在試用期 [#判斷訂閱是否在試用期]

收到 `subscription.activated` 時，檢查 `trial_ends_at` 欄位：

```typescript
async function handleSubscriptionActivated(data: SubscriptionPayload) {
  if (data.trial_ends_at) {
    // 試用期訂閱 - status 為 trialing
    console.log(`試用期到 ${data.trial_ends_at}`);
    // 可自行排程提醒顧客試用即將到期
  } else {
    // 一般訂閱 - status 為 active
    console.log('訂閱已啟用');
  }
}
```

subscription.trial_ending 事件 [#subscriptiontrial_ending-事件]

<Callout type="warn">
  **即將推出**

  `subscription.trial_ending` 事件目前尚未上線。此事件預計在試用期到期前 3 天自動觸發，提醒開發者即將進行正式扣款。

  **目前的替代方案：** 收到 `subscription.activated` 事件時，讀取 `trial_ends_at` 欄位，在您的系統中自行排程提醒通知。
</Callout>

Payload 範例 [#payload-範例]

**試用期 subscription.activated：**

```json
{
  "id": "evt_sub_activated_trial_001",
  "type": "subscription.activated",
  "timestamp": "2024-01-15T10:05:30.000Z",
  "data": {
    "id": "sub_trial123",
    "customer": {
      "id": "cus_xyz789",
      "external_id": "my_user_456",
      "email": "user@example.com",
      "name": "王小明"
    },
    "product_id": "prod_pro",
    "price_id": "price_pro_monthly",
    "status": "trialing",
    "original_amount": 299,
    "discount": null,
    "amount": 299,
    "interval": "month",
    "interval_count": 1,
    "next_billing_date": "2024-01-29T00:00:00.000Z",
    "trial_ends_at": "2024-01-29T00:00:00.000Z",
    "current_period_start": "2024-01-15T00:00:00.000Z",
    "current_period_end": "2024-01-29T00:00:00.000Z",
    "created_at": "2024-01-15T10:05:00.000Z",
    "updated_at": "2024-01-15T10:05:30.000Z"
  }
}
```

詳細 Webhook payload 格式請參考 [Webhook 事件類型](/guides/webhooks/events)。

***

後台設定 [#後台設定]

1. 前往「商品管理」→ 選擇或新增商品
2. 選擇「訂閱制」
3. 啟用「試用期」
4. 設定試用天數（如 7 天、14 天、30 天）
5. 儲存並發布

***

最佳實踐 [#最佳實踐]

1. **設定合理的試用天數** - 太短無法充分體驗，太長降低轉換急迫性。7-14 天是常見選擇
2. **搭配提醒機制** - 在試用即將到期前發送通知，提醒顧客即將扣款
3. **提供試用期內的引導** - 透過 Email 系列引導顧客探索產品核心功能
4. **追蹤試用轉換率** - 監控從 `trialing` 到 `active` 的轉換率
5. **考慮搭配優惠碼** - 針對特定客群提供延長試用或首期特價