> ## 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.

# サブスクリプションは実際にいつ課金されますか？

> Waffo がサブスクリプションの開始から各請求日をどう算出するか、31 日に開始した月次サブスクリプションが 2 月の後に 31 日へ戻る理由、遅れた再試行が次の日付を動かすかどうか、初回期間の失敗が再試行されない理由、そして期間ごとの課金ステータスそれぞれの意味。

本ページは**タイミング**についてのページです：各期間がどの日に課金され、その日がどう動くか。再試行ポリシーと決済手段の動作は[サブスクリプションの再試行と決済手段](/docs/ja/support/subscription-retry-and-payment-methods-faq)に、金額は[サブスクリプションの金額と期間ごとのスケジューリング](/docs/ja/support/subscription-amount-scheduling-faq)に記載されています。

## 更新の課金は実際にいつ開始されますか？

Waffo はサブスクリプションに**次回課金タイムスタンプ**を保存し、そのタイムスタンプを過ぎた後の定期スイープでその期間の課金を開始します。ここから 2 つのことが導かれます。

* 日付は確定的ですが、**時刻は確定的ではありません**。照合とユーザーへの案内は、分単位ではなく日単位で計画してください。
* 保存されているサブスクリプションのすべてのタイムスタンプ — 次回課金時刻、期間の開始と終了、サブスクリプションの終了時刻 — は **UTC** で、API は ISO 8601 形式で返します。請求カレンダーが現地時間の場合は、お客様側で変換してください。加盟店ごとの請求タイムゾーン設定はありません。

サブスクリプションを「ユーザーのタイムゾーンで 09:00 に課金する」ように固定する方法はありません。最も近い制御手段は `/api/v1/subscription/create` の `startTime` で、これがスケジュール全体の基準となるアンカーを設定します — [サブスクリプションの作成と検証](/docs/ja/support/subscription-creation-validation-faq)を参照してください。

## 2 回目以降の請求日はどのように導出されますか？

**サブスクリプションの開始時刻**に、サイクルを丸ごと加算して求めます。

```
charge date of period n = subscription start + (n − 1) × (periodInterval × periodType unit)
```

前回の課金が成功した日付からではなく、前の期間の日付から順に進めるのでもありません。すべての期間が同じアンカーから計算されるため、遅れて課金された期間がその後の期間をずらすことはなく、丸めが期間から期間へ累積することもありません。

使用されるサイクルは**その期間番号に対して有効なサイクル**です。別のトライアルサイクルを設定している場合、トライアル期間は開始からトライアルサイクルで数えられ、通常の期間はトライアル終了から通常サイクルで数えられます。切り替えはトライアルが終了する期間番号で行われます。

## 31 日に開始した月次サブスクリプションは、2 月にはどうなりますか？

**短い月ではその月の最終有効日に丸められ、その後は 31 日に戻ります。**

すべての期間は*開始 + n か月*として計算されるため、1 月 31 日に 1 か月を加えると 2 月 28 日（閏年は 29 日）になります — 2 月 31 日は存在しません — が、2 か月を加えると 3 月 31 日、3 か月を加えると 4 月 30 日になります。丸めは着地する月にのみ適用され、新しいアンカーにはなりません。

| 期間 | 予定日 |
| - | - |
| 1 | 1 月 31 日 |
| 2 | 2 月 28 日（丸め） |
| 3 | 3 月 31 日 |
| 4 | 4 月 30 日（丸め） |
| 5 | 5 月 31 日 |

これは月末サブスクリプションで最も多く見られる想定外の動作です：**サブスクリプションは確かに 31 日に戻ります。** 31 日に開始したユーザーは毎月の最終日 — その月にある 28 日、29 日、30 日、31 日のいずれか — に課金されます。このようなサブスクリプションに対して、固定の日付を前提としたリマインダーを構築しないでください。

安定した日付での請求が商品にとって重要な場合は、すべての月に存在する日（1〜28 日）にサブスクリプションを開始するか、「今」にアンカーを決めさせるのではなく `startTime` を明示的に設定してください。

## ある期間が 3 日間の再試行の後にようやく成功しました。次の期間は動きますか？

**デフォルトでは動きません。** 次の期間は上記のとおりサブスクリプションの開始から計算されるため、再試行で回復した期間が以降のスケジュールを後ろにずらすことはありません — ユーザーが日数を得ることはありません。

代わりに**スケジュールを実際の支払い時刻に再基準化するアカウントレベルの設定**があります。有効化されている場合、更新が成功するとその課金が成功した時点から次回課金日が再計算され、サブスクリプションの終了日もあわせて再計算されます。これについて知っておくべきことは 2 点です。

* スケジュールを動かすのは**前方**のみです。再計算された日付が保存されている日付より早い場合は、保存されている日付が維持されます。
* これは Portal ではなく、Waffo が収単契約上で設定します。「ユーザーは実際に支払った日から常にフルサイクルを得る」という動作が必要な場合は、どちらかを前提に構築する前に、お客様のアカウントにどの動作が設定されているかを Waffo の担当者に確認してください。

2 つの動作は異なる日付を生成するため、次回課金日をご自身で導出しないでください。各期間の後に `/api/v1/subscription/inquiry` から `nextPaymentDateTime` を読み取ってください。

## 「次回課金」のリマインダーにはどの日付フィールドを読むべきですか？

| フィールド | 意味 | 変わるタイミング |
| - | - | - |
| `startDateTime` | サブスクリプションが開始した時刻 | 一度だけ書き込まれます |
| `currentPeriod` | サブスクリプションが現在いる期間番号 | 次の期間が開かれると進みます |
| `nextPaymentDateTime` | **次の**期間の予定課金時刻 | `currentPeriod` とともに進みます。**最終期間では進みません**。**更新が保留されている間は `null` で返されます** |
| `endDateTime` | サブスクリプションの最終期間が終了する時刻 | 総期間数が確定したときに書き込まれます。スケジュールが再基準化されると再計算されます |

つまり、リマインダーには `nextPaymentDateTime` を読んでください。ただし、ユーザーに日付を約束する前に 2 つのケースを処理してください。

* **`null` は「これ以上課金がない」という意味ではありません。** Waffo はサブスクリプションの更新が保留されている間 — 例えば現在の期間がまだ試行中である、またはプラン変更がその期間に対して保留中であるなど — `null` を返します。保留が解除されると日付は再び表示されます。`null` は*完了*ではなく*まだ不明*として扱ってください。
* **最終期間では、値は将来ではなく古いものです。** そこでは進まないため、最終期間自身の日付が引き続き表示されます。ユーザーに再度課金されると伝える前に、`currentPeriod` をサブスクリプションの最終期間数と照合するか、`endDateTime` を確認してください。

「このサブスクリプションは終了したか」については、**ステータス**を読んでください — [サブスクリプションの作成と検証](/docs/ja/support/subscription-creation-validation-faq)の終了ステータスが答えであり、日付フィールドではありません。

## 期間ごとの課金ステータスは何を意味しますか？

各請求期間には独自の注文があり、独自のステータスを持ちます。Portal ではこれらを *Initial*、*To Pay*、*Retrying*、*Paid*、*Closed* と表示します。

| ステータス | Portal の表示 | 意味 |
| - | - | - |
| `INIT` | Initial | 期間の注文は存在しますが、まだ支払いに提出されていません。 |
| `TO_PAY` | To Pay | 提出済み。決済結果を待っています。 |
| `NEED_RETRY` | Retrying | 試行が失敗し、次の試行が予定されています。 |
| `PAY_SUCCESS` | Paid | 期間の回収が完了しました。最終です。 |
| `ORDER_CLOSE` | Closed | 期間は回収されません — 再試行が尽きた、またはクローズされました。最終です。 |

ラベルより重要な 2 つのルールがあります。

* `PAY_SUCCESS` と `ORDER_CLOSE` が**唯一の**最終ステータスです。それ以外はまだ変わる可能性があります。
* 期間が `ORDER_CLOSE` に達しても、サブスクリプション自体のステータスは変わり**ません**。サブスクリプションは `ACTIVE` のままで、次の期間は予定どおり試行されます。権利付与の判断は、これらの期間ごとの結果からお客様が行うものです。[サブスクリプションの再試行と決済手段](/docs/ja/support/subscription-retry-and-payment-methods-faq)を参照してください。

## 最初の課金がまったく再試行されなかったのはなぜですか？

即時開始のサブスクリプションの初回課金は、バックグラウンドの更新ではなく**ユーザー在席型**の決済だからです。失敗した場合、その期間の注文は直ちにクローズされます。再試行スケジュールも、バックアップ決済手段の試行も、ユーザーへの決済失敗メールもありません。

その理由は、ユーザーがまさにその場にいるからです — 正しい回復方法は、ユーザーに再度試してもらうか別の決済手段を試してもらうことであり、ユーザーが失敗を見ているカードを再試行することではありません。

| ケース | 初回課金の動作 |
| - | - |
| サブスクリプションが即時開始 | 失敗すると再試行なしで期間がクローズされます |
| サブスクリプションに将来の `startTime` がある | アクティベーション課金はバックグラウンドの更新として**扱われます**。バックアップが試行され、再試行スケジュールが適用されます |

2 行目が、人がつまずく例外です。開始が遅延されたサブスクリプションは事前に認可され、後でユーザー不在のまま課金されるため、その初回課金は以降のすべての課金と同じように動作します。

即時開始のケースの回復方法は、ユーザーが別の決済手段を選んだ後に**新しい**サブスクリプションを作成することです。同じ期間に対して別のワンタイム注文を作成し、サブスクリプションがそれを認識することを期待しないでください。

## 待つのではなく、失敗した期間をユーザー自身に支払わせることはできますか？

**特定の失敗した期間を回収する加盟店向けエンドポイントはありません。** サブスクリプション API は `create`、`inquiry`、`cancel`、`manage`、`change`、`change/inquiry`、`update` で構成されており — いずれも期間の課金を再駆動せず、「今すぐ支払う」や「再支払い」の呼び出しはありません。

実際にできることは次のとおりです。

| 目的 | 方法 |
| - | - |
| 失敗した期間を回収する | 再試行スケジュールを実行させます。次の試行で課金できるものがあるように、ホスト型管理ページでユーザーに決済手段を追加または修正してもらいます。 |
| ユーザーに今すぐ何かを請求する | 通常の**ワンタイム注文**を作成します。これは別の取引であり、サブスクリプションの期間には紐付きません。 |
| ユーザーを別のプランや価格に移す | `/api/v1/subscription/change` — [サブスクリプションのプラン変更](/docs/ja/support/subscription-plan-change-faq)を参照。 |
| 請求を停止する | `/api/v1/subscription/cancel`。 |

有効な決済手段を追加することが最も価値の高い行動です。紐付けられたバックアップは、再試行間隔を待つのではなく、次の失敗時に**直ちに**試行されるからです。

## 再試行ポリシーを Portal で自分で変更できますか？

いいえ。再試行戦略 — サイクルごとの間隔と最大試行回数 — は収単契約上にあり、Waffo が設定します。それを書き換える Portal 画面も API もないため、セルフサービスでは変更できず、リクエストごとのパラメータでもありません。

契約上の他のスケジュールを形作る設定についても同様です。上記の支払い後の再基準化の動作、およびサブスクリプションがキャンセルされたときに保留中の再試行をクローズするかどうかです。3 つすべてがアカウントレベルです。いずれかが変更された場合、既存のサブスクリプションにも適用されるのか、新規のものだけなのかを明確に確認してください — 答えはどの設定かによって異なり、誤った前提を置くことが照合が崩れる原因になります。

## 実際のサイクルを待たずに、これらすべてをテストするにはどうすればよいですか？

サンドボックスの更新シミュレーターを使用してください。サブスクリプションをアクティブ化し、`/api/v1/subscription/manage` で管理 URL を取得して開き、次回支払いシミュレーションのコントロールで 1 期間ずつ進めます。1 クリックが 1 期間なので、「期間 2 は成功、期間 3 は失敗」のように連鎖させることができます。詳細と予約されたテスト金額は[サンドボックスシミュレーター](/docs/ja/developer-docs/tools-and-references/developer-tools/sandbox-simulator)と[サンドボックステスト](/docs/ja/support/sandbox-testing-faq)に記載されています。

サンドボックスで**できない**のは実際の時計を早送りすることです。そのため上記の月末の動作は、待つのではなく、シミュレートした各期間の後に `nextPaymentDateTime` を読み取ることで検証するのが最善です — 31 日に開始したサブスクリプションは、2 月には 28 日／29 日、3 月には再び 31 日を示すはずです。


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