> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# サブスクリプション FAQ

> Waffo のサブスクリプションに関する最もよくある質問への回答：アップグレードとダウングレード、金額の変更、引き落としの失敗とリトライ、通知、トライアル、ユーザー側での管理。

このページでは、Waffo のサブスクリプションについて加盟店から最もよく寄せられる質問に回答します。項目レベルの仕様は
[Subscription API 仕様](/docs/api-reference/introduction) にあります。

## ユーザーのプランをアップグレードまたはダウングレードするにはどうすればよいですか？

`/api/v1/subscription/change` を呼び出します。変更リクエストは**元のサブスクリプションを基にした新しいサブスクリプション**を
作成し、元のサブスクリプションの残額は新しいものに充当されます — 手動でキャンセルして作り直す必要はありません。

* 結果は `/api/v1/subscription/change/inquiry` で追跡してください。
* 変更が完了すると、Waffo は `SUBSCRIPTION_CHANGE_NOTIFICATION` も送信します。

## `change`、`update`、`manage` の違いは何ですか？

| API | 使う場面 |
| - | - |
| `/api/v1/subscription/change` | ユーザーが**プラン**を切り替える（アップグレード / ダウングレード）とき。新しいサブスクリプションを作成し、残額を引き継ぎます。 |
| `/api/v1/subscription/update` | 既存のサブスクリプションの**金額**だけを調整する必要があるとき：定期課金額、トライアル期間の金額、期間ごとの予定金額。プランの切り替えも、新しいサブスクリプションの作成もありません。 |
| `/api/v1/subscription/manage` | **エンドユーザー**に、自分のサブスクリプションを確認・解約できるホスト型ページを提供したいとき。Waffo が管理 URL を返すので、そこへユーザーをリダイレクトします。各 URL には独自の有効期限があり、`expiredAt` として返されます。 |

金額の更新は契約上の上限に対して検証されます。

## 期間ごとに異なる金額を請求できますか？

はい。2 つの仕組みを組み合わせて、段階的な価格設定や初回期間の特典に対応できます。

* **トライアル期間** — サブスクリプション作成時に `trialPeriodAmount` と `numberOfTrialPeriod` を設定します。
  トライアルの粒度は `trialPeriodType` と `trialPeriodInterval` でカスタマイズできます。
* **予定金額** — 特定の正規期間（たとえば割引される初回期間）について、作成時または後から
  `/api/v1/subscription/update` で期間ごとの金額を設定します。

ある期間に予定金額が設定されていない場合は、サブスクリプションの基本 `amount` が適用されます。

## 引き落としが失敗しました。次に何が起きますか？

失敗した引き落としは、サブスクリプションのリトライ戦略に従って自動的にリトライされます — お客様がリトライを
起動する必要はありません。

* 失敗理由、タイムスタンプ、リトライの詳細を含むすべての決済試行は、**サブスクリプション決済注文の通知**で送信されます。
* 各請求期間の最終結果だけが必要な場合は、代わりに `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` を購読してください —
  期間ごとに 1 回、最終結果とともに送信され、途中のリトライイベントはスキップされます。

具体的なリトライのスケジュールと上限は、契約に設定されたリトライ戦略によって異なります。お客様のアカウントの正確な
ポリシーが必要な場合は、インテグレーションサポートにお問い合わせください。

## どのサブスクリプション通知を購読すべきですか？

| 通知 | レベル | 使う場面 |
| - | - | - |
| サブスクリプションステータス通知 | サブスクリプション | サブスクリプションのライフサイクル状態（作成、解約、期限切れ）を知る必要があるとき。 |
| サブスクリプション決済注文通知 | 決済注文 | 失敗とリトライを含め、すべての決済試行を完全に把握する必要があるとき。 |
| `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` | 請求期間 | 各期間の最終結果だけが必要なとき。 |
| `SUBSCRIPTION_CHANGE_NOTIFICATION` | 変更リクエスト | アップグレード / ダウングレードの結果が必要なとき。 |
| `SUBSCRIPTION_UPDATE_NOTIFICATION` | 金額の更新 | `/api/v1/subscription/update` の成功後に、サブスクリプションの `notifyUrl` へ送信されます（シート追加のチャージが成功した場合を含む）。照会 API が返すのと同じサブスクリプションを、新しい金額とともに含みます。 |

いずれの通知でも、処理後に `success` を返してください。Waffo が `failed` または `unknown` を受け取った場合、
Waffo は翌日にかけて分散したバックオフのスケジュールで通知をリトライします。スケジュールは
[Webhook のリトライ](/docs/ja/developer-docs/webhook/retry) を参照してください。

## ユーザーはどのようにサブスクリプションを解約しますか？

2 つの経路があります。

* **加盟店から** — `/api/v1/subscription/cancel` を呼び出します。
* **ユーザーから** — `/api/v1/subscription/manage` で取得したホスト型管理ページへユーザーをリダイレクトすると、
  そこで詳細の確認と解約ができます。
* **ウォレット側から** — ユーザーがウォレットアプリ内で支払いの認可を取り消すと、ウォレットが Waffo に通知します。
  取り消された決済手段がそのサブスクリプションで唯一のものだった場合、サブスクリプションは自動的に解約されます。
  バックアップの決済手段がある場合は、そちらがデフォルトになります。これはサブスクリプションステータス通知で
  お客様に通知されるため、サブスクリプションがまだ有効かどうかについては、自社の記録ではなく Webhook を正としてください。

サブスクリプションが解約状態に到達すると、新しい請求期間は開かれません。すでに保留中のリトライが即座に破棄されるかどうかは
契約上の設定によります — 重要な場合はインテグレーションサポートに確認してください。

## Waffo は日次請求や異通貨のサブスクリプションに対応していますか？

どちらも対応しています。

* `DAILY` は他の請求サイクルと並ぶサポート済みの `periodType` です。
* 異通貨のサブスクリプションは `userCurrency` 項目でサポートされます — ユーザーは自国通貨で支払います。

決済手段ごとの機能と制限は、[Subscription API 仕様](/docs/api-reference/introduction) の付録に記載されています。

## `subscriptionManagementUrl` には何を渡すべきですか？

`subscriptionManagementUrl` はサブスクリプション作成時に必須として文書化されており、常に送信すべきです。
ただし、サーバーは現在これを省略したリクエストを**拒否しません** — 省略は検証エラーとしては現れず、後から
お客様のページへ誘導する顧客向けメールのリンクが欠落する形で現れます。**デスクトップブラウザで**ユーザーが開けるページを
指定してください。アプリのディープリンクはここでは不適切です：PC で開いたユーザーがページにまったくたどり着けない
可能性があります。選択肢は 3 つあります。

* 自社で認証付きのサブスクリプション管理ページを構築し、その URL を渡す。
* Waffo が `/api/v1/subscription/manage` から返すホスト型ページを自社のページでラップし、その URL を渡す。
* Waffo のホスト型管理ページをそのまま使う。

このページは**機能の入口であり、決済フローのステップではありません**。リアルタイムの取引中に表示されるものではなく、
サブスクリプションの決済が成功した後に — ユーザーのアカウント画面、注文確認ページ、その他サイト上の適切な場所で —
提示するものです。

## サブスクリプションの通知を受け取りましたが、直後に照会するとサブスクリプションが `ACTIVE` ではありません

サブスクリプションの状態は**結果整合性**です。通知が届いた時点では内部の状態更新がまだ収束中のことがあるため、
その直後に発行した照会は、まだ `ACTIVE` ではないステータスを返すことがあります。これは読み取りのタイミングの影響であり、
サブスクリプションの失敗ではありません。

次のように扱ってください。

* 最初の照会結果を最終的なものとして扱わないでください。少し待ってから再照会してください。
* 状態変化のトリガーとしてはサブスクリプションステータス通知を優先し、照会は判断のためではなく確認のために使ってください。

## トライアル期間の金額を通常の金額と同じにできますか？

いいえ。作成時、`trialPeriodAmount` は `amount` より**厳密に小さく**なければなりません。等しい値は
`trial period amount should be less than subscription amount` というメッセージのパラメーターエラーで拒否されます。
ゼロは有効なトライアル金額（無料トライアル）なので、受け付けられる範囲は `0 ≤ trialPeriodAmount < amount` です。

価格を変えずに請求カレンダーをずらすことがトライアルの目的であれば、トライアルはまったく設定せず、
`startTime` で初回の請求を遅らせるか、`scheduledAmounts` で初期の特定期間の価格を設定してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.