# 訂閱制 (/features/payments/subscriptions)





訂閱制 [#訂閱制]

訂閱制是最常見的數位商業模式，顧客定期自動扣款，讓您建立穩定的 MRR（月度經常性收入）。

適用場景 [#適用場景]

* **會員制內容** - 付費電子報、會員專屬文章
* **SaaS 軟體** - 月繳/年繳訂閱方案
* **線上課程** - 課程庫訂閱制
* **社群會員** - 付費 Discord、會員俱樂部

功能特點 [#功能特點]

彈性計費週期 [#彈性計費週期]

支援多種計費週期：

| 週期 | 說明          |
| -- | ----------- |
| 月繳 | 每月自動扣款      |
| 季繳 | 每 3 個月扣款    |
| 年繳 | 每年扣款，通常提供折扣 |
| 自訂 | 自訂天數週期      |

試用期 [#試用期]

提供免費試用期，讓顧客先體驗再決定：

* 設定試用天數（如 7 天、14 天、30 天）
* 結帳時以 **NT$2 信用卡驗證**確認卡片有效（自動退還，不實際扣款）
* 試用期結束自動轉為正式訂閱，扣取全額
* 試用期間可隨時取消
* 試用期間切換方案不涉及差額計算，新價格在試用到期時生效

完整說明請參考[試用期文件](/features/payments/trials)。

<Callout type="info">
  **免綁卡兌換**：搭配 100% 折扣優惠碼和 `collectPaymentMethod: 'if_required'`，顧客可以不需要信用卡就完成訂閱。此時不會進行 NT$2 驗證。詳見[零元結帳](/guides/checkout/hosted-checkout#零元結帳免綁卡兌換)。
</Callout>

方案升降級 [#方案升降級]

顧客可自行升級或降級方案：

* **升級** - 立即生效，按比例計算差額
* **降級** - 下個計費週期生效

重複訂閱防護 [#重複訂閱防護]

Recur 會自動防止同一客戶重複訂閱同一商品。當開發者在建立結帳時帶入 `customerEmail`，系統會檢查該客戶是否已有以下狀態的訂閱：

* **ACTIVE** — 正常訂閱中
* **TRIAL** — 試用期中
* **PAST\_DUE** — 逾期但尚未取消

若偵測到重複，API 回傳 `409 conflict` 錯誤，包含現有訂閱的 ID。已取消（CANCELED）或已過期（EXPIRED）的訂閱不影響重新訂閱。

詳細的錯誤處理方式請參考[錯誤處理指南](/guides/checkout/error-handling#處理重複訂閱錯誤409)。

後台設定 [#後台設定]

1. 前往「商品管理」→「新增商品」
2. 選擇「訂閱制」
3. 設定：
   * 商品名稱與描述
   * 價格與計費週期
   * 試用期（可選）
4. 儲存並發布

技術整合 [#技術整合]

建立訂閱結帳 [#建立訂閱結帳]

```typescript
const response = await fetch('https://api.recur.tw/v1/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    productId: 'prod_xxx',
    mode: 'SUBSCRIPTION',
    successUrl: 'https://your-site.com/success',
    cancelUrl: 'https://your-site.com/cancel',
    // 選填：預先套用優惠碼
    // promotionCode: 'SAVE100',
  }),
});
```

匯入既有訂閱 [#匯入既有訂閱]

透過 `POST /v1/subscriptions` 搭配 `status: ACTIVE`，可直接建立已生效的訂閱，適用於：

* 從其他平台（綠界、Stripe）遷移
* 為既有免費用戶建立訂閱
* 從人工管理轉系統化

支援自訂計費週期（`billing_anchor_date` / `next_billing_date`）、金額覆寫（`amount`）和開發者自訂資料（`metadata`）。

詳細請參考 [Subscriptions API](/api/subscriptions#建立訂閱)。

相關 Webhook 事件 [#相關-webhook-事件]

* `subscription.created` - 訂閱建立
* `subscription.activated` - 訂閱啟用
* `subscription.cancelled` - 訂閱取消（顧客/管理員主動取消）
* `subscription.revoked` - 訂閱因付款失敗被撤銷
* `subscription.payment_method_required` - 訂閱到期但無付款方式（匯入的訂閱）
* `invoice.paid` - 發票付款成功
* `invoice.payment_failed` - 發票付款失敗

詳細請參考 [Webhook 文件](/guides/webhooks)。