> ## 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 がサブスクリプション契約者に直接送信できる 6 種類のメール、それぞれが送信される正確なタイミング、どの言語で表示されるか、自社メールとの重複を避ける方法、そしてサブスクリプション請求履歴が返す内容。

Waffo は、サブスクリプションのライフサイクルにおける 6 つの時点で、契約者に直接メールを送信できます。
本ページは**それらのメール**について説明します — 何がメールを送信させるのか、そしてユーザーに
すべてを二重に送ってしまうことを避ける方法です。Waffo が*お客様の*サーバーに送信する Webhook については、
[サブスクリプション FAQ](/docs/ja/support/subscription-faq) の通知一覧表を、リトライ動作については
[サブスクリプションのリトライと決済手段](/docs/ja/support/subscription-retry-and-payment-methods-faq) を参照してください。

## Waffo は契約者にどのメールを送信しますか？

6 種類あり、それぞれ独立したオン／オフスイッチを持ちます — そのため、アカウントに対して任意の組み合わせを
有効にできます：

| メール | 送信されるタイミング |
| - | - |
| サブスクリプション有効化 | サブスクリプションが**最初の**請求期間で `ACTIVE` に達したとき。 |
| トライアル終了間近 | トライアル期間の終了直前。 |
| 次回支払いのお知らせ | 各引き落としの直前。**トライアル期間も含みます**。 |
| 支払い失敗 | 引き落とし試行が失敗したとき — 条件があります。下記を参照。 |
| サブスクリプション解約 | 解約が完了したとき。 |
| サブスクリプション変更 | 更新 API を通じて金額を変更したとき。 |

6 行目は、最も多くの連携で見落とされているものです。すでに自社でユーザーに価格変更のメールを送っている場合は、
自社メールを送る前に、アカウントで**サブスクリプション変更**メールが有効になっていないか確認してください。

## それぞれ正確にはいつ送信されますか？

6 つのうち 3 つはイベント駆動で、イベント発生から間もなく届きます。2 つは日次ジョブで実行されるため、
正確なオフセットではなく、ある時間幅の中で届きます。1 つはお客様自身の API 呼び出しによって同期的にトリガーされます。

| メール | 仕組み | 信頼できるタイミング |
| - | - | - |
| サブスクリプション有効化 | イベント駆動 | `ACTIVE` への遷移時、最初の期間のみ。開始を遅らせたサブスクリプションがゼロ金額のオーソリで有効化された場合も送信されます。 |
| トライアル終了間近 | 日次ジョブ | 1 回のみ。短い先読み幅（数日）以内にトライアル終了を検出した最初の日次実行時。サブスクリプションが `ACTIVE` で、かつ実際にトライアル中の場合のみ送信されます。 |
| 次回支払いのお知らせ | 日次ジョブ | 期間ごとに 1 回。先読み幅（約 1 日）以内に次回の引き落としを検出した最初の日次実行時。最終期間には送信されません。 |
| 支払い失敗 | イベント駆動 | 次のセクションを参照。 |
| サブスクリプション解約 | イベント駆動 | 解約が確定した後、いずれの解約ステータスでも。 |
| サブスクリプション変更 | 更新呼び出しと同期 | 更新によって定期金額、トライアル金額、または期間ごとの予定金額が実際に変更されたとき。 |

2 つのリマインダーメールは**先読み幅に対する日次ジョブ**によって駆動されるため、そのオフセットは
おおよそのものとして扱ってください。「ちょうど N 時間前にご連絡します」のようなユーザー向けの約束を
これらの上に構築しないでください。また、自社のスケジューリングの時計として使わないでください。

## 支払い失敗メールは本当にすべての失敗で送信されますか？

いいえ。そう仮定すると重複排除が誤ったものになります。次の 2 つの場合には抑制されます：

* **最初の期間の失敗では送信されません。** 最初の引き落としが失敗したサブスクリプションでは、
  ユーザーへの失敗メールは生成されません。その時点でユーザーに知らせたい場合は、お客様側で行う必要があります。
* **最終でもなく、間隔ベースのリトライスケジュールの一部でもない試行では送信されません。** 実務上、
  これは即時のバックアップ決済手段による試行が無通知であることを意味します。試したバックアップカードごとに
  ユーザーにメールが送られることはありません。

送信されるもの：スケジュールされた各リトライ試行と、期間をクローズする最終試行です。メールにはユーザーが
決済手段を追加・更新するためのリンクが含まれており、通常はそれがユーザーに取ってほしい行動です。

## サブスクリプション変更メールは何がトリガーで、何が含まれますか？

お客様自身によるサブスクリプション更新 API の呼び出しが、定期金額、トライアル金額、または期間ごとの
予定金額のいずれかを変更したときです。ジョブではなく、その呼び出しと同期して送信されます。

メールでは、金額が以前いくらで、今いくらになり、どの期間から新しい金額が適用されるかをユーザーに伝えます。
期間ごとのスケジュールを変更した場合は、変更前と変更後の両方のスケジュールが含まれます。

設計時に考慮すべき 2 つの帰結：

* **プラン変更**（変更 API によるアップグレード／ダウングレード）は別の操作であり、このメールは送信されません。
  [サブスクリプション FAQ](/docs/ja/support/subscription-faq) の変更／更新の区別を参照してください。
* トリガーがお客様の API 呼び出しであるため、1 つのサブスクリプションに対して複数の更新を短時間に連続して行うと、
  複数のメールが送信されることがあります。ユーザーに見せたい変更 1 つにつき、更新呼び出しを 1 回にしてください。

## これらのメールはどの言語で送信されますか？

受信者の言語は次の順序で決定されます：

1. サブスクリプションに指定した**チェックアウト言語**（設定している場合）。
2. それ以外の場合、サブスクリプションの **`userCurrency`** — ユーザーが実際に課金される通貨 — から導出されます。
3. どちらからも対応ロケールが得られない場合は英語。

実務上のルール：**上書きしない限り、`userCurrency` が言語を決めます。** ユーザーの言語が請求通貨と
連動しない場合 — たとえば現地通貨で課金される英語話者のユーザー — は、導出に頼らず、サブスクリプションに
チェックアウト言語を明示的に設定してください。

同じロケールはメール内のサブスクリプション管理リンクにも適用されるため、ユーザーは同じ言語のページに到達します。

## テンプレートを編集したり、個別のメールを自分でオフにできますか？

Merchant Portal からはできません。現在のリリースでは：

* 6 つのスイッチは**Waffo がアカウントごとに設定**するもので、セルフサービスではありません。
  6 つのうちどれをオンにしたいか、どれを自社で担いたいかを Waffo の担当者にお伝えください。
* テンプレート自体は**加盟店が編集できません**。反映されるのはお客様の**ブランディング**です — 加盟店名と、
  チェックアウト用に設定したロゴ／外観がメールに適用されるため、ブランドのないメールにはなりません。

自社で管理する文言が必要な場合、正しいパターンは、対応する Waffo メールをオフにしてもらい、同じイベントの
Webhook から自社メールを送ることです。

## Waffo のメールと自社メールの重複を避けるにはどうすればよいですか？

上の表を基に、イベントごとに担当者を決めてください。確実なアプローチは：

| 自社で担いたいもの | 対応 |
| - | - |
| 有効化／ウェルカムメッセージ | 有効化メールをオフにしてもらい、サブスクリプションステータス通知から自社メールを送ります。 |
| 更新リマインダー | 次回支払いメールをオフにしてもらいます。オフセットを自社で制御できます（日次ジョブでは制御できません）。 |
| 督促シーケンス | 支払い失敗メールをオフにしてもらい、決済注文通知から自社メールを送ります。この通知はメールが抑制するものも含めて*すべての*試行を報告します。 |
| 価格変更のお知らせ | サブスクリプション変更メールをオフにしてもらいます。呼び出しを行ったのはお客様なので、変更が起きたことはすでにわかっています。 |

自社メールのタイミングを調整して Waffo のメールを抑え込もうとしないでください — 2 つのリマインダーメールは
固定オフセットではなく、時間幅の中で届きます。

## 各ユーザー向けメールに対応する Webhook はどれですか？

すべてのユーザー向けメールには、お客様が処理できるサーバー側の対応物があります。これが「メールをオフにして
自社で送る」というパターンを実現可能にしています：

| ユーザー向けメール | 自社メールの起点 |
| - | - |
| サブスクリプション有効化 | `ACTIVE` への遷移時のサブスクリプションステータス通知。 |
| トライアル終了間近 | サブスクリプションのトライアル設定から計算した自社スケジュール — リマインダーごとの Webhook はありません。 |
| 次回支払いのお知らせ | サブスクリプションの期間設定から計算した自社スケジュール。 |
| 支払い失敗 | サブスクリプション決済注文通知。メールが抑制するものも含めて**すべての**試行を報告します。 |
| サブスクリプション解約 | いずれかの解約ステータスにおけるサブスクリプションステータス通知。 |
| サブスクリプション変更 | `SUBSCRIPTION_UPDATE_NOTIFICATION`、およびお客様自身の更新呼び出しへのレスポンス。 |

2 つのリマインダーには対応する Webhook がありません。これらはイベントではなく予測だからです。
自社で制御するオフセットでリマインダーを送りたい場合は、サブスクリプション自体から計算してください。

## ユーザーがメールを受け取っていないと言っています。何を確認すべきですか？

次の順序で確認してください — 最初の 3 つでほぼすべてのケースが説明できます：

1. **そのスイッチはアカウントでオンになっていますか？** 6 つはすべて独立して設定可能で Waffo が設定するため、
   オンだと思っているメールがオンでない可能性があります。これを最初に確認してください。
2. **抑制されるケースに該当しますか？** 最初の期間の失敗では失敗メールは送信されず、バックアップ決済手段による
   試行でも送信されません。最初の課金が失敗したユーザーが何も受け取っていないのは正当な動作です。
3. **タイミングは想定どおりですか？** 2 つのリマインダーメールは先読み幅に対する日次ジョブから送信されるため、
   「想定したオフセットにちょうど届かなかった」は想定される動作であり、メールの欠落ではありません。
4. **言語はユーザーの期待どおりですか？** 予期しない言語のメールは「メールが来ていない」と報告されることがあります。
   サブスクリプションの `userCurrency` と、チェックアウト言語を設定したかどうかを確認してください。
5. **イベント自体は実際に発生しましたか？** 上記の対応する Webhook で確認してください — サブスクリプションが
   `ACTIVE` に達していなければ、探すべき有効化メールは存在しません。

## サブスクリプション請求履歴は何を返しますか？

2 つの異なるビューがあり、誤った方を選ぶのはよくある連携ミスです。

**加盟店向け照会 API** は、期間ごとに意図的に小さなフィールドセットを返します。サブスクリプション照会で
`paymentDetails=1` を渡すと取得できます：

| フィールド | 意味 |
| - | - |
| `acquiringOrderId` | その期間の注文 — 取引および返金への結合キー。 |
| `period` | 期間番号。 |
| `orderCurrency` / `orderAmount` | お客様の価格設定通貨での金額。 |
| `orderStatus` | その期間の結果。 |
| `orderUpdatedAt` | その期間の注文の最終変更。 |
| `topupDetails` | シート追加課金があった期間のみ：その期間内に行われたトップアップ注文。それぞれ独自の `acquiringOrderId`、`topupAmount`、`orderStatus` を持ちます。 |

**含まれない**ものに注意してください：トライアルフラグ、ユーザー通貨やユーザー金額、期間の開始／終了日、
失敗コードはありません。それらが必要な場合は注文自体が必要です — `acquiringOrderId` で照会してください。

ユーザーが見る**ホスト型サブスクリプション管理ページ**は、より豊富な期間ごとの行を表示します。トライアルフラグ、
両方の通貨／金額ペア、期間の開始と終了、紐づけられた決済手段のマスク済みカード情報と有効期限、領収書リンク、
ユーザー向けの失敗理由が含まれます。このビューはユーザー向けのものです。API の一部として扱わないでください。


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