---
title: "サブスクリプションの連携"
description: "このガイドでは、トライアルなし・トライアル期間ありの両方のフローについて、サブスクリプションの作成、有効化、そして更新が自動的に行われるようにする方法を説明します。"
source: "https://docs.tokenz.one/ja/v2/subscriptions/get-started"
api_version: "v2"
locale: "ja"
version_status: "current"
docs_stage: "prod"
---

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

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

## 前提条件

Tokenz ダッシュボードから API シークレットキーを取得してください。単発決済をまだ連携していない場合は [チェックアウト](https://docs.tokenz.one/ja/v2/checkout) をご覧ください — サブスクリプションは同じ 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`。詳細は [ライフサイクルと請求](https://docs.tokenz.one/ja/v2/subscriptions/lifecycle#%E7%9D%A3%E4%BF%83%EF%BC%88%E6%94%AF%E6%89%95%E3%81%84%E5%A4%B1%E6%95%97%E3%81%8B%E3%82%89%E3%81%AE%E5%9B%9E%E5%BE%A9%EF%BC%89) をご覧ください。
- `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 セキュア認証の完了
- 今後の更新に必要な継続課金の同意の取得（[決済方法と同意](https://docs.tokenz.one/ja/v2/subscriptions/payment-methods) を参照）
- **トライアル期間なし**：初回注文を即座に課金し、サブスクリプションを有効化
- **トライアル期間あり**：課金を行わずにトライアルを開始

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

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

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

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

Webhook を受信して、ご自身の記録を同期させてください — 成功時は `subscription.trial_started`、`subscription.activated`、`subscription.renewed`、課金が失敗した場合は `subscription.unpaid` です。詳細は [Webhook](https://docs.tokenz.one/ja/v2/subscriptions/webhooks) をご覧ください。

```mermaid
sequenceDiagram;
autonumber;
participant C as 消費者;
participant M as 加盟店サーバー;
participant T as Tokenz API;
participant TC as Tokenz ホストのチェックアウト;
participant W as 加盟店の Webhook ハンドラー;
M->>T: POST /v2/checkoutsession（subscription ブロックを含む）;
T-->>M: checkoutSession + subscription（created）;
M-->>TC: 消費者をチェックアウトセッションの URL にリダイレクト;
TC->>TC: カード情報の収集、地域・税金の解決、同意の取得;
alt トライアル期間なし
TC->>TC: 初回注文を課金し、サブスクリプションが active になる;
else トライアル期間あり
TC->>TC: サブスクリプションが trialing になる（まだ課金なし）;
Note over T: trialEnd に達すると、Tokenz が最初の注文を自動的に作成・課金;
T->>T: サブスクリプションが active になる;
end
TC-->>C: successUrl / pendingUrl / cancelUrl にリダイレクト;
T->>W: webhook: subscription.trial_started / subscription.activated;
loop 各請求期間ごと;
T->>T: 更新注文を作成し、保存済みカードに自動課金;
T->>W: webhook: subscription.renewed（失敗時は subscription.unpaid）;
end
```

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

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

## テスト

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