---
title: "変更と照会"
description: "サブスクリプションのエンドポイントは、大きく2つに分かれます。"
source: "https://docs.tokenz.one/ja/v2/subscriptions/modification"
api_version: "v2"
locale: "ja"
version_status: "current"
docs_stage: "prod"
---

# 変更と照会

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

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

- [サブスクリプション一覧の取得](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E3%82%B5%E3%83%96%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E4%B8%80%E8%A6%A7%E3%81%AE%E5%8F%96%E5%BE%97)と[サブスクリプションの取得](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E3%82%B5%E3%83%96%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E5%8F%96%E5%BE%97) — サブスクリプションを表示します。
- [サブスクリプションの注文一覧の取得](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E3%82%B5%E3%83%96%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E6%B3%A8%E6%96%87%E4%B8%80%E8%A6%A7%E3%81%AE%E5%8F%96%E5%BE%97)と[請求書リンク](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E8%AB%8B%E6%B1%82%E6%9B%B8%E3%83%AA%E3%83%B3%E3%82%AF) — 注文履歴と請求書を表示します。
- [プラン変更一覧の取得](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E3%83%97%E3%83%A9%E3%83%B3%E5%A4%89%E6%9B%B4%E4%B8%80%E8%A6%A7%E3%81%AE%E5%8F%96%E5%BE%97) — 未完了のプラン変更を表示します。
- [サブスクリプションの解約](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E3%82%B5%E3%83%96%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E8%A7%A3%E7%B4%84)と[プラン変更のキャンセル](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E3%83%97%E3%83%A9%E3%83%B3%E5%A4%89%E6%9B%B4%E3%81%AE%E3%82%AD%E3%83%A3%E3%83%B3%E3%82%BB%E3%83%AB) — 加盟店側でサブスクリプションまたは保留中の変更をキャンセルします。

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

- [消費者による解約のリクエスト](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E6%B6%88%E8%B2%BB%E8%80%85%E3%81%AB%E3%82%88%E3%82%8B%E8%A7%A3%E7%B4%84%E3%81%AE%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88) — 消費者の希望に応じて解約します。
- [プラン変更のリクエスト](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E3%83%97%E3%83%A9%E3%83%B3%E5%A4%89%E6%9B%B4%E3%81%AE%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88) — 消費者が新しいプランを承認します。
- [支払い方法変更のリクエスト](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E6%94%AF%E6%89%95%E3%81%84%E6%96%B9%E6%B3%95%E5%A4%89%E6%9B%B4%E3%81%AE%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88) — 消費者が新しいカードを入力します。

**金額の形式：** `amount`などの金額項目は、各通貨の最小補助単位で表されます。詳しくは[対応通貨](https://docs.tokenz.one/ja/v2/checkout/currency)をご覧ください。

結果は、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`が送信されます。解約は取り消せません。アクセス権と進行中の注文がどうなるかは、[ライフサイクルと請求](https://docs.tokenz.one/ja/v2/subscriptions/lifecycle#%E8%A7%A3%E7%B4%84)をご覧ください。

```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`にリダイレクトしてください。新しいカードに対する同意は、そのホストページで取得されます。詳しくは[決済方法と同意](https://docs.tokenz.one/ja/v2/subscriptions/payment-methods)をご覧ください。

ボディは、消費者による解約と同じ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`によるページ送りは、[サブスクリプション一覧の取得](https://docs.tokenz.one/ja/v2/subscriptions/modification#%E3%82%B5%E3%83%96%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E4%B8%80%E8%A6%A7%E3%81%AE%E5%8F%96%E5%BE%97)と同じです。`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](https://docs.tokenz.one/ja/v2/subscriptions/webhooks)をご覧ください。