サブスクリプションの連携

このガイドでは、トライアルなし・トライアル期間ありの両方のフローについて、サブスクリプションの作成、有効化、そして更新が自動的に行われるようにする方法を説明します。

前提条件

Tokenz ダッシュボードから API シークレットキーを取得してください。単発決済をまだ連携していない場合はチェックアウトをご覧ください — サブスクリプションは同じ Checkout Session のフローの上に構築されています。

1. サブスクリプションのチェックアウトセッションを作成する

継続契約の詳細を指定する subscription ブロックを含む Checkout Session を作成します。サブスクリプションのチェックアウトには、値引きのない単一の商品のみを設定できます。

bash

curl --request POST \
  --url https://api.tokenz.one/v2/checkoutsession \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "itemDetails": [{
      "product": {
        "price": { "amount": 1000, "currency": "USD" },
        "quantity": 1,
        "label": "Pro Plan (Monthly)",
        "images": ["https://example.com/pro-plan.png"],
        "taxCategory": "SAAS"
      }
    }],
    "subscription": {
      "interval": { "unit": "MONTH", "count": 1 },
      "trialPeriodDays": 7,
      "dunningMode": "RETRY"
    },
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel",
    "customerInfo": {
      "emailAddress": "consumer@example.com"
    }
  }'

サブスクリプションのパラメーター

interval（必須）：請求間隔。unit（WEEK、MONTH、または YEAR）と count（1以上の整数。更新間隔の単位数）を持つオブジェクトです。例えば { "unit": "MONTH", "count": 1 } は毎月更新を表します。
trialPeriodDays（任意、1〜365）：最初の課金までの日数。トライアルなしの場合は省略します。
dunningMode（任意）：RETRY（デフォルト）または CANCEL_IMMEDIATELY。詳細はライフサイクルと請求をご覧ください。
dunningMaxAttempts（任意、デフォルト3）、dunningExpireAfterHours（任意、デフォルト24）：dunningMode が RETRY の場合にのみ使用されます。

レスポンス

json

{
  "id": "checkoutsession_1p4LPTRKB5Z",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/1p4LPTRKB5Z",
  "test": false,
  "subscription": {
    "id": "subscription_1p4LS47fB1h",
    "object": "subscription",
    "status": "created",
    "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 },
    "createdAt": "2026-07-01T00:00:00Z",
    "updatedAt": "2026-07-01T00:00:00Z"
  }
}

注： trialPeriodDays を省略した場合、レスポンスには初回課金のための order オブジェクトも含まれます。

2. 消費者をリダイレクトしてセットアップを完了させる

消費者を返却された url にリダイレクトします。以降の消費者向けフローは、Tokenz がホストするチェックアウトページが処理します。

消費者の地域、通貨、適用される税金の解決
カード情報の収集と、発行会社が求める 3D セキュア認証の完了
今後の更新に必要な継続課金の同意の取得（決済方法と同意を参照）
トライアル期間なし：初回注文を即座に課金し、サブスクリプションを有効化
トライアル期間あり：課金を行わずにトライアルを開始

このステップが完了すると、Tokenz は結果に応じて消費者を successUrl、pendingUrl、または cancelUrl にリダイレクトします — これは単発の Checkout Session と同じリダイレクトの仕組みです。

3. 更新と有効化は自動的に行われます

これ以上何かを呼び出す必要はありません。

トライアルがなかった場合、初回課金が成功すると同時にサブスクリプションは active になります。
トライアルが設定されていた場合、Tokenz はトライアル終了時に最初の注文を自動的に作成・課金し、成功するとサブスクリプションを有効化します。
それ以降は、サブスクリプションが active である限り、Tokenz は各請求期間の終了時に新しい注文を自動的に作成し、課金します。

Webhook を受信して、ご自身の記録を同期させてください — 成功時は subscription.trial_started、subscription.activated、subscription.renewed、課金が失敗した場合は subscription.unpaid です。詳細は Webhook をご覧ください。

図

サブスクリプションの確認

Tokenz ダッシュボードを使用して、アカウント全体のサブスクリプションを確認・管理できます。ご自身のシステムでは、ポーリングを行わずに各サブスクリプションのステータスを最新の状態に保つために、上記の Webhook イベントをご利用ください。

テスト

テスト用の API キー（test_ プレフィックス）を使用してテスト用のサブスクリプションを作成できます。テスト用のエンティティ ID には _t のサフィックスが付きます（例：subscription_1p4LS47fB1h_t）。
テストモードでは、ホストされたチェックアウトページ上で認証結果（承認・拒否）をシミュレートできるため、実際のカードネットワークを使わずにハッピーパスと督促・復旧の両方を検証できます。
Tokenz ダッシュボードでは、通常の請求スケジュールを待たずに、テスト用サブスクリプションの更新課金をオンデマンドでトリガーすることもできます。