変更と照会

サブスクリプションのエンドポイントは、大きく2つに分かれます。

直接の照会と変更。 これらの呼び出しはCheckout Sessionを使いません。サブスクリプション、その注文履歴と請求書リンク、未完了のプラン変更を表示するときや、加盟店側の判断でサブスクリプションや保留中のプラン変更をキャンセルするときに使います。直接の解約は即時に反映されます。

サブスクリプション一覧の取得とサブスクリプションの取得 — サブスクリプションを表示します。
サブスクリプションの注文一覧の取得と請求書リンク — 注文履歴と請求書を表示します。
プラン変更一覧の取得 — 未完了のプラン変更を表示します。
サブスクリプションの解約とプラン変更のキャンセル — 加盟店側でサブスクリプションまたは保留中の変更をキャンセルします。

消費者が確定するリクエスト。 これらの呼び出しはCheckout Sessionを返します。消費者をそのurlにリダイレクトしてください。消費者が確定するまで、サブスクリプションは変更されません。消費者の操作や同意が必要な変更、つまり消費者が解約を希望した場合、プラン変更を消費者に承認してもらう必要がある場合、新しい支払い方法を入力してもらう必要がある場合に使います。

消費者による解約のリクエスト — 消費者の希望に応じて解約します。
プラン変更のリクエスト — 消費者が新しいプランを承認します。
支払い方法変更のリクエスト — 消費者が新しいカードを入力します。

金額の形式： amountなどの金額項目は、各通貨の最小補助単位で表されます。詳しくは対応通貨をご覧ください。

結果は、APIキーの加盟店とテストモードに一致するものに限られます。

サブスクリプション一覧の取得

GET /v2/subscriptionは、認証済みの加盟店のサブスクリプションをIDの新しい順に返します。

referenceとcustomerIdは完全一致で、両方を指定するとAND条件になります。limitは1〜100で、デフォルトは20です。最初のページではcursorを省略し、次のページを取得するときはpagination.nextCursorの値をそのままcursorに渡してください。

bash

curl --request GET \
  --url 'https://api.tokenz.one/v2/subscription?customerId=customer_123&limit=20' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

レスポンス

json

{
  "data": [
    {
      "id": "subscription_1p4LS47fB1h_t",
      "object": "subscription",
      "status": "active",
      "test": true,
      "reference": "Pro Plan (Monthly)",
      "customerId": "customer_123",
      "items": [
        {
          "id": "item_1p4LS47fB1i_t",
          "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 },
      "provideAccess": true,
      "currentBillingPeriodEnd": "2026-08-01T00:00:00Z",
      "createdAt": "2026-07-01T00:00:00Z",
      "updatedAt": "2026-07-01T00:00:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "subscription_1p4LC47fB2a_t"
  }
}

最後のページではpagination.nextCursorは含まれません。

サブスクリプションの取得

GET /v2/subscription/{id}は、1件のサブスクリプションを返します。IDが存在しない場合、他の加盟店のものである場合、またはAPIキーのテストモードと一致しない場合は404で失敗します。

bash

curl --request GET \
  --url https://api.tokenz.one/v2/subscription/subscription_1p4LS47fB1h_t \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

レスポンス

json

{
  "id": "subscription_1p4LS47fB1h_t",
  "object": "subscription",
  "status": "active",
  "test": true,
  "reference": "Pro Plan (Monthly)",
  "customerId": "customer_123",
  "items": [
    {
      "id": "item_1p4LS47fB1i_t",
      "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 },
  "provideAccess": true,
  "currentBillingPeriodEnd": "2026-08-01T00:00:00Z",
  "createdAt": "2026-07-01T00:00:00Z",
  "updatedAt": "2026-07-01T00:00:00Z"
}

サブスクリプションの解約

POST /v2/subscription/{id}/cancelは、サブスクリプションを即時に解約します。リクエストボディはありません。解約できるのは、サブスクリプションがtrialing、active、unpaidのいずれかの場合です。すでにcanceledのサブスクリプションには何も起こらず、それ以外のステータスではコードsubscription.status-invalidの422が返されます。

解約するとcanceledAtが設定され、以降の更新注文は作成されなくなり、subscription.canceledが送信されます。解約は取り消せません。アクセス権と進行中の注文がどうなるかは、ライフサイクルと請求をご覧ください。

bash

curl --request POST \
  --url https://api.tokenz.one/v2/subscription/subscription_1p4LS47fB1h_t/cancel \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

レスポンス

json

{
  "id": "subscription_1p4LS47fB1h_t",
  "object": "subscription",
  "status": "canceled",
  "test": true,
  "items": [
    {
      "id": "item_1p4LS47fB1i_t",
      "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 },
  "provideAccess": true,
  "provideAccessUntil": "2026-08-01T00:00:00Z",
  "canceledAt": "2026-07-15T12:00:00Z",
  "createdAt": "2026-07-01T00:00:00Z",
  "updatedAt": "2026-07-15T12:00:00Z"
}

消費者による解約のリクエスト

POST /v2/subscription/{id}/request/cancelは、サブスクリプションそのものは解約しません。消費者が解約を確定するためのCheckout Sessionを作成します。返されたurlに消費者をリダイレクトしてください。消費者が確定すると、subscription.canceled Webhookを含め、直接の解約と同じようにサブスクリプションが解約されます。

必須のボディフィールド：

successUrl：消費者が確定した後の遷移先。
pendingUrl：確定がまだ保留中の場合の遷移先。
cancelUrl：消費者がフローを途中で離脱した場合の遷移先。

themeは任意です（LIGHTまたはDARK）。

bash

curl --request POST \
  --url https://api.tokenz.one/v2/subscription/subscription_1p4LS47fB1h_t/request/cancel \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel"
  }'

レスポンス

201でCheckout Sessionが返されます。消費者が確定するまで、サブスクリプションは現在のステータスのままです。

json

{
  "id": "checkoutsession_1p4LC47fB2a_t",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/1p4LC47fB2a_t",
  "successUrl": "https://example.com/success",
  "pendingUrl": "https://example.com/pending",
  "cancelUrl": "https://example.com/cancel",
  "test": true,
  "subscription": {
    "id": "subscription_1p4LS47fB1h_t",
    "object": "subscription",
    "status": "active"
  },
  "createdAt": "2026-07-15T12:00:00Z",
  "updatedAt": "2026-07-15T12:00:00Z"
}

支払い方法変更のリクエスト

POST /v2/subscription/{id}/request/payment-method-changeは、消費者が新しいカードを入力するためのCheckout Sessionを作成します。消費者をurlにリダイレクトしてください。新しいカードに対する同意は、そのホストページで取得されます。詳しくは決済方法と同意をご覧ください。

ボディは、消費者による解約と同じ3つのリダイレクトURL（successUrl、pendingUrl、cancelUrl）と、任意のthemeです。

サブスクリプションがunpaidの場合、返されるセッションは未払いの注文のチェックアウトです。その注文の支払いが完了すると、支払い方法が置き換えられ、サブスクリプションが再開されます。成功すると、Tokenzはsubscription.activated Webhookを送信します。

activeまたはtrialingのサブスクリプションでは、支払い方法を更新するためのCheckout Sessionが返されます。成功すると、Tokenzはsubscription.payment_method_updated Webhookを送信します。

bash

curl --request POST \
  --url https://api.tokenz.one/v2/subscription/subscription_1p4LS47fB1h_t/request/payment-method-change \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel"
  }'

レスポンス

json

{
  "id": "checkoutsession_1p4LP47fB3b_t",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/1p4LP47fB3b_t",
  "successUrl": "https://example.com/success",
  "pendingUrl": "https://example.com/pending",
  "cancelUrl": "https://example.com/cancel",
  "test": true,
  "subscription": {
    "id": "subscription_1p4LS47fB1h_t",
    "object": "subscription",
    "status": "active"
  },
  "createdAt": "2026-07-15T12:00:00Z",
  "updatedAt": "2026-07-15T12:00:00Z"
}

プラン変更のリクエスト

POST /v2/subscription/{id}/request/plan-changeは、新しい商品と請求間隔の承認を消費者に求めます。返されたCheckout Sessionで消費者が承認するまで、変更は適用されません。

サブスクリプションはactiveまたはtrialingである必要があり、それ以外の状態ではコードsubscription.status-invalidの422が返されます。ボディにはitemDetails、replacementMode、successUrl、pendingUrl、cancelUrlを含める必要があります。 itemDetailsはサブスクリプションの現在の商品を置き換えます。値引きのない商品を1つだけ、quantityを1にして指定してください。商品の通貨はサブスクリプションの通貨と一致している必要があり、一致しない場合はコードcurrency.inconsistentの400エラーが返されます。 intervalは新しい請求間隔を{ "unit": "WEEK" | "MONTH" | "YEAR", "count": <integer ≥ 1> }の形式で指定します。 successUrlは即時の変更が適用された後に、pendingUrlは繰り延べの変更が承認された後に使われます。

replacementMode：

IMMEDIATE_PRORATION：期間型のサブスクリプション（例：プレミアムプラン）向けで、消費者が注文の決済を承認した時点で変更を適用します。サブスクリプションがactiveの場合、現在の請求期間の残り分が日割りで消費者にクレジットされ、請求基準日は決済が承認された日に変わります。サブスクリプションがtrialingの場合、追加のクレジットなしでトライアルが直ちに終了し、新しいプランでサブスクリプションが始まります。計算されたクレジットが新しい商品の価格を上回る場合は、コードsubscription.plan-replacement-invalidの422エラーが返されます。アイテム型のサブスクリプション（例：毎月の通貨購入）にはこのモードを使わないでください。アイテム型のサブスクリプションでアップグレードの選択肢を提供したい場合は、Tokenzにお問い合わせください。
DEFERRED：現在の請求期間が終了した後に変更を適用します。承認されるとsubscription.plan_change_scheduledが送信され、次の請求期間の注文の支払いが完了した時点でプランが変わります。

プランが適用されると（即時でも次の期間でも）、Tokenzはsubscription.plan_changed Webhookを送信します。

bash

curl --request POST \
  --url https://api.tokenz.one/v2/subscription/subscription_1p4LS47fB1h_t/request/plan-change \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "itemDetails": [{
      "product": {
        "price": { "amount": 2000, "currency": "USD" },
        "quantity": 1,
        "label": "Pro Plan (Yearly)",
        "images": ["https://example.com/pro-plan.png"],
        "taxCategory": "SAAS"
      }
    }],
    "interval": { "unit": "YEAR", "count": 1 },
    "replacementMode": "DEFERRED",
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel"
  }'

同じプランを消費者の承認後すぐに適用するには、"replacementMode": "IMMEDIATE_PRORATION"を使います。このモードは期間型のサブスクリプションに使い、アイテム型には使わないでください。

レスポンス

201でCheckout Sessionと保留中の変更が返されます。

json

{
  "id": "checkoutsession_1p4LR47fB4c_t",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/1p4LR47fB4c_t",
  "successUrl": "https://example.com/success",
  "pendingUrl": "https://example.com/pending",
  "cancelUrl": "https://example.com/cancel",
  "test": true,
  "subscriptionChange": {
    "id": "subscriptionchange_1p4LC9aB2cD_t",
    "object": "subscriptionchange",
    "status": "pending",
    "replacementMode": "DEFERRED",
    "interval": { "unit": "YEAR", "count": 1 },
    "items": [
      {
        "id": "item_1p4LS47fB1j_t",
        "detail": {
          "product": {
            "price": { "amount": 2000, "currency": "USD" },
            "quantity": 1,
            "label": "Pro Plan (Yearly)",
            "images": ["https://example.com/pro-plan.png"]
          }
        }
      }
    ]
  },
  "createdAt": "2026-07-15T12:00:00Z",
  "updatedAt": "2026-07-15T12:00:00Z"
}

消費者をurlにリダイレクトしてください。後で変更を一覧表示したりキャンセルしたりする場合は、subscriptionChange.idを保存しておいてください。

プラン変更一覧の取得

GET /v2/subscription/{id}/plan-changeは、サブスクリプションの未完了の変更、つまりステータスがpendingまたはapprovedの変更を返します。canceledとappliedの変更は含まれません。

変更は、pending（消費者の承認待ち）、approved（承認済みで、繰り延べの変更の場合はまだ適用されていない状態）、applied、canceledの順に進みます。

bash

curl --request GET \
  --url https://api.tokenz.one/v2/subscription/subscription_1p4LS47fB1h_t/plan-change \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

レスポンス

json

{
  "data": [
    {
      "id": "subscriptionchange_1p4LC9aB2cD_t",
      "object": "subscriptionchange",
      "status": "approved",
      "replacementMode": "DEFERRED",
      "interval": { "unit": "YEAR", "count": 1 },
      "items": [
        {
          "id": "item_1p4LS47fB1j_t",
          "detail": {
            "product": {
              "price": { "amount": 2000, "currency": "USD" },
              "quantity": 1,
              "label": "Pro Plan (Yearly)",
              "images": ["https://example.com/pro-plan.png"]
            }
          }
        }
      ]
    }
  ]
}

プラン変更のキャンセル

POST /v2/subscription/{id}/plan-change/{changeId}/cancelは、適用前のpendingまたはapprovedの変更をキャンセルします。リクエストボディはありません。 applied、expired、canceledの変更をキャンセルしようとすると、subscription.change-status-invalidの422が返されます。繰り延べの変更は、ステータスがまだapprovedであっても、次の請求期間の注文が作成された時点でキャンセルできなくなります。このような変更をキャンセルしようとすると、subscription.change-status-invalidの422が返されます。

すでに承認済みの繰り延べの変更をキャンセルすると、subscription.plan_change_canceledが送信されます。

bash

curl --request POST \
  --url https://api.tokenz.one/v2/subscription/subscription_1p4LS47fB1h_t/plan-change/subscriptionchange_1p4LC9aB2cD_t/cancel \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

レスポンス

json

{
  "id": "subscriptionchange_1p4LC9aB2cD_t",
  "object": "subscriptionchange",
  "status": "canceled",
  "replacementMode": "DEFERRED",
  "interval": { "unit": "YEAR", "count": 1 },
  "items": [
    {
      "id": "item_1p4LS47fB1j_t",
      "detail": {
        "product": {
          "price": { "amount": 2000, "currency": "USD" },
          "quantity": 1,
          "label": "Pro Plan (Yearly)",
          "images": ["https://example.com/pro-plan.png"]
        }
      }
    }
  ]
}

サブスクリプションの注文一覧の取得

OrderサービスのGET /v2/orderは、1つのサブスクリプションに対して作成された注文を一覧で返します。subscriptionIdは必須です。limit（1〜100、デフォルト20）とcursorによるページ送りは、サブスクリプション一覧の取得と同じです。pagination.nextCursorの値をそのままcursorに渡してください。注文はIDの新しい順に並び、APIキーのテストモードに一致するものだけが返されます。

各注文にはsubscriptionIdが含まれます。商品には、その注文が対象とする期間を示すbilledPeriodStart（その時刻を含む）とbilledPeriodEnd（その時刻を含まない）が含まれる場合があります。

bash

curl --request GET \
  --url 'https://api.tokenz.one/v2/order?subscriptionId=subscription_1p4LS47fB1h_t&limit=20' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

レスポンス

json

{
  "data": [
    {
      "id": "order_1D5xA9BnKfv_t",
      "object": "order",
      "status": "succeeded",
      "test": true,
      "subscriptionId": "subscription_1p4LS47fB1h_t",
      "amount": { "amount": 1000, "currency": "USD" },
      "items": [
        {
          "id": "item_1p4LO47fB1k_t",
          "billedPeriodStart": "2026-07-01T00:00:00Z",
          "billedPeriodEnd": "2026-08-01T00:00:00Z",
          "detail": {
            "product": {
              "price": { "amount": 1000, "currency": "USD" },
              "quantity": 1,
              "label": "Pro Plan (Monthly)",
              "images": ["https://example.com/pro-plan.png"]
            }
          }
        }
      ],
      "createdAt": "2026-07-01T00:00:00Z",
      "updatedAt": "2026-07-01T00:00:05Z"
    }
  ],
  "pagination": {
    "nextCursor": "order_1p4LC47fB2a_t"
  }
}

請求書リンク

GET /v2/order/{id}/invoiceは、サブスクリプションの更新注文を含む注文について、購入者向けにホストされた請求書のリンクを返します。displayUrlはホストされた請求書ページです。downloadUrlはPDFで、PDFが生成された後にのみ含まれます。顧客をリダイレクトするときは、Tokenzが生成した署名を含むフラグメント部分まで含めた完全なURLを使ってください。

bash

curl --request GET \
  --url https://api.tokenz.one/v2/order/order_1D5xA9BnKfv_t/invoice \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

レスポンス

json

{
  "displayUrl": "https://invoice.tokenz.one/i/1D5xA9BnKfv_t#generated-invoice-signature",
  "downloadUrl": "https://invoice.tokenz.one/i/1D5xA9BnKfv_t/download#generated-invoice-signature"
}

PDFが生成されるまでは、レスポンスにはdisplayUrlのみが含まれます。

Webhook

これらのエンドポイントをポーリングするのではなく、Webhookで自社の記録を同期してください。このページの操作に関連するイベントは次のとおりです。

subscription.canceled — 直接の解約、または消費者が確定した解約が完了しました。
subscription.payment_method_updated — 消費者が新しいカードを確定しました。
subscription.plan_change_scheduled — 消費者が繰り延べのプラン変更を承認しました。
subscription.plan_change_canceled — 予定されていた繰り延べのプラン変更が、適用前にキャンセルされました。
subscription.plan_changed — 即時または繰り延べのプラン変更が適用されました。ペイロードのitemsとintervalは新しいプランを表します。

ペイロードの形式はWebhookをご覧ください。