訂閱 Webhook

訂閱會針對每一次生命週期轉換發送 webhook 事件，讓您的後端無需輪詢即可保持同步。本頁列出了訂閱相關的專屬事件及其負載結構。

關於如何註冊 webhook 端點、驗證簽章以及處理正式/測試模式，請參見 Webhook 和開始使用 Webhook——訂閱事件使用與訂單、退款、爭議和兌換事件完全相同的事件信封與傳遞機制。

金額格式： webhook 負載中的金額以每種貨幣的最小輔助單位表示。參見支援的貨幣。

範例事件負載

以下範例展示了訂閱成功續訂時發送的事件。

json

{
  "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "object": "subscription.renewed",
  "createdAt": "2026-07-01T00:00:00Z",
  "test": false,
  "eventData": {
    "type": "subscription",
    "version": "v2",
    "data": {
      "subscription": {
        "id": "subscription_1p4LS47fB1h",
        "object": "subscription",
        "status": "active",
        "test": false,
        "items": [
          {
            "id": "item_1p4LS47fB1i",
            "detail": {
              "product": {
                "price": { "amount": 1000, "currency": "USD" },
                "quantity": 1,
                "label": "Pro Plan (Monthly)",
                "images": ["https://example.com/pro-plan.png"]
              }
            }
          }
        ],
        "interval": { "unit": "MONTH", "count": 1 },
        "currentBillingPeriodEnd": "2026-08-01T00:00:00Z",
        "createdAt": "2026-06-01T00:00:00Z",
        "updatedAt": "2026-07-01T00:00:00Z"
      }
    }
  }
}

負載中始終包含事件發生時訂閱的完整目前狀態（而非差異）。請使用頂層的 id 進行傳遞追蹤和冪等處理，並使用 eventData.data.subscription.id 將事件與您自己的記錄相關聯。

事件類型

subscription.trial_started: 消費者提供了卡片資訊並開始了訂閱的試用期。訂閱現在為 trialing。
subscription.activated: 訂閱的首次扣款成功（可能是在無試用期的結帳時，也可能是在試用期結束時）。訂閱現在為 active。
subscription.renewed: 一次週期性續訂扣款成功，訂閱進入下一個計費週期。
subscription.unpaid: 一次週期性（或初始）扣款失敗或需要付款。訂閱現在為 unpaid，催收流程已開始。
subscription.payment_method_updated: 訂閱的支付方式已成功更新（新卡片的授權已獲核准）。
subscription.plan_change_scheduled: 一次遞延方案變更已獲消費者核准，將在下一個計費週期開始時生效。
subscription.plan_change_canceled: 一次先前排程的遞延方案變更在生效前被取消。
subscription.plan_changed: 一次方案變更（立即或遞延）已套用到訂閱。負載中的 items 和/或 interval 反映了新方案。
subscription.canceled: 訂閱已由商戶代表消費者取消。之後不會再產生任何扣款。
subscription.expired: 訂閱因始終無法收款（催收已耗盡，或初始扣款從未成功）而終止。

建議處理方式

subscription.activated 和 subscription.renewed：為目前計費週期授予或延長產品存取權限。
subscription.unpaid：可以選擇在您自己的產品介面中提醒消費者注意支付問題；Tokenz 已經自動處理了重試和向消費者發送郵件的工作。
subscription.payment_method_updated：如果您快取了支付方式的中繼資料，請更新您自己的記錄；無需其他操作即可保持訂閱正常計費。
subscription.plan_changed：更新權益以符合新方案的商品。
subscription.canceled 和 subscription.expired：在目前計費週期結束時（或根據您產品的政策立即）撤銷存取權限，並更新您自己的訂閱狀態以反映該終止狀態。