サブスクリプション 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：任意で、自社プロダクトの UI 上で消費者に支払いの問題への対応が必要であることを警告できます。再試行や消費者へのメール送信は Tokenz がすでに自動的に処理しています。
subscription.payment_method_updated：支払い方法のメタデータをキャッシュしている場合は、ご自身の記録を更新してください。サブスクリプションの課金を継続するために追加の対応は不要です。
subscription.plan_changed：新しいプランの商品に合わせて権限を更新してください。
subscription.canceled および subscription.expired：現在の請求期間の終了時点（または自社プロダクトのポリシーに応じて即座に）でアクセスを取り消し、ご自身のサブスクリプションのステータスを終端状態に合わせて更新してください。