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

# ホスト型サブスクリプション管理ページ

> /subscription/manage の仕組み：どのステータスでリンクが返り、なぜ A0028 になるのか、リンクの有効期間と新しいリンクが古いものを無効にするかどうか、顧客がページで正確に何を見て何ができるのか、どこまでブランディングできるのか、そしてページでのキャンセルが即時である理由。

Waffo は、顧客が自身のサブスクリプションを確認し、紐づく決済手段を管理し、キャンセルできるページをホストしています。
URL は `/api/v1/subscription/manage` から取得し、顧客をそこへ送ります。Waffo がお客様の顧客に送るメールからも
リンクできます。[顧客へのサブスクリプションメール](/docs/ja/support/subscription-notifications-faq) を参照してください。

## どのサブスクリプションの管理リンクを取得できますか？

有効なサブスクリプションとして実際に存在したことのあるもの — すでに終了したものを含みます。

| サブスクリプションのステータス | `/subscription/manage` |
| - | - |
| `ACTIVE` | リンクを返す |
| `MERCHANT_CANCELLED`、`USER_CANCELLED`、`CHANNEL_CANCELLED`、`PLATFORM_CANCELLED` | リンクを返す |
| `EXPIRED` | リンクを返す |
| `IN_PROGRESS` | 拒否 — `A0028` |
| `AUTHORIZATION_REQUIRED` | 拒否 — `A0028` |
| `CLOSE` | 拒否 — `A0028` |

## `A0028` はどういう意味ですか？

> `A0028` — Subscription is still in progress or has failed and management url is
> not available

サブスクリプションが一度も有効にならなかったことを意味します。顧客が確認を完了していない、まだマンデートを承認していない、
または有効化される前にサブスクリプションが終了した、のいずれかです。管理するものがないため、リンクは発行されません。

これは権限や設定のエラーでは**なく**、ステータスが変わらない限り再試行しても解決しません。代わりに行うこと：

* `IN_PROGRESS` / `AUTHORIZATION_REQUIRED` — 顧客はまだ承認を完了していません。管理リンクではなく、作成レスポンスの
  `subscriptionAction.webUrl` へ送ってください。
* `CLOSE` — サブスクリプションは終了しており、復活できません。新しく作成してください。

## キャンセル済みや期限切れのサブスクリプションでもページを開けますか？

はい。それは意図的な設計です。顧客はプランと課金履歴を引き続き確認できます。キャンセル後に顧客が求めるのは、
たいていまさにそれです。

そこでできないのは操作です。`ACTIVE` でないサブスクリプションでは決済手段の変更は拒否され、キャンセルするものも残っていません。
そのため、終了したサブスクリプションのページは読み取り専用の記録であり、再購読の入口ではありません。戻ってきた顧客が
プランを再開したい場合は、`/api/v1/subscription/create` による新しいサブスクリプションになります。

## リンクはどのくらい有効ですか？ 新しいリンクは古いリンクを無効にしますか？

`/api/v1/subscription/manage` を呼び出すごとに、**新しい独立した**リンクが発行されます。各リンクには独自の有効期限があり、
レスポンスがそれを伝えます。

| レスポンスフィールド | 用途 |
| - | - |
| `managementUrl` | 顧客に送るリンク |
| `expiredAt` | そのリンクの有効期限。ISO 8601、UTC |
| `subscriptionStatus` | リンク発行時点でのサブスクリプションのステータス |

設計時に考慮すべき結果：

* **新しいリンクを発行しても、以前のリンクは無効になりません。** 数分差で発行された 2 つのリンクは、それぞれの `expiredAt` が
  過ぎるまで両方とも機能します。すでに送ったリンクを取り消すために `manage` を再度呼び出すことに頼らないでください。
* **`expiredAt` を読み取ってください。有効期間をハードコードしないでください。** この期間は短く、契約ではなく設定です。
  リンクは受け渡しであり、ブックマークではありません。保存しておいて後でメールするのではなく、顧客がクリックする瞬間に
  発行してください。
* `manage` を繰り返し呼び出しても問題ありません。サブスクリプションへの副作用はありません。

Waffo が**自身の**顧客向けメールに入れるリンクは動作が異なります。有効期間はかなり長いものの、新しいメールにはそれぞれ
鮮度マーカーが付いており、**以前のメールのリンクを無効にします**。そのため、先月のメールを掘り出した顧客はそのリンクが
使えない一方、最新のメールは機能する、ということがあります。この無効化はメールのリンク同士の間でのみ適用され、
API で発行したリンクには一切影響しません。

## Waffo のメールを、Waffo のページではなく自社の管理ページに向けることはできますか？

はい。Waffo の顧客向けメール内の管理リンクが **Waffo のホスト型ページ**を指すか、**お客様が指定した URL** を指すかは
アカウントごとの設定です。

| 設定 | メールのリンク先 |
| - | - |
| Waffo のページ（デフォルト） | 新たに発行されたリンクを持つホスト型ページ |
| お客様のページ | `/subscription/create` で送信した `subscriptionManagementUrl` |

これが `subscriptionManagementUrl` の用途であり、このフィールドがアプリのディープリンクではなく、顧客がデスクトップブラウザーで
開けるものを指すべき理由です。設定の切り替えはセルフサービスのトグルではなく、Waffo の担当者への依頼になります。

メールから管理リンクを完全に取り除く設定はありません。Waffo のメールで顧客をどこにも誘導したくない場合、取れる手段はメール自体を
オフにして自社からメールを送ることです。[顧客へのサブスクリプションメール](/docs/ja/support/subscription-notifications-faq) を
参照してください。

## 顧客はページで実際に何を見て、何ができますか？

**見る** — プランとその課金履歴を、加盟店向け照会 API が返すより詳細に：

| ページ上の項目 | 補足 |
| - | - |
| プランの説明、金額、周期 | サブスクリプションに設定されたとおり |
| ステータス | サブスクリプションの現在のステータス |
| 紐づいている決済手段 | 該当する場合、マスクされたカード情報と有効期限 |
| 期間ごとの課金履歴 | 期間番号、両方の通貨/金額のペア、期間の開始と終了、トライアルのマーカー、失敗した期間には顧客向けの失敗理由 |
| 期間ごとの領収書リンク | **0 以外の金額が回収された**期間にのみ存在 — 検証用と 0 金額の行には存在しない |

**する** — 3 つのこと：

| 操作 | 利用可否 |
| - | - |
| サブスクリプションをキャンセルする | `ACTIVE` の間 |
| 決済手段の追加、別のデフォルトの設定、バックアップの並べ替え、決済手段の削除 | カード、Apple Pay、Google Pay のサブスクリプションで、`ACTIVE` の間。現在のデフォルトは削除できない |
| 次回の更新をシミュレートする | サンドボックスのみ — [サンドボックステスト](/docs/ja/support/sandbox-testing-faq) を参照 |

決済手段のルールと、追加すると 0 金額の注文が作成される理由は
[サブスクリプションの再試行と決済手段](/docs/ja/support/subscription-retry-and-payment-methods-faq) にあります。

## 決済手段の管理を、自社のバックエンドから行うことはできますか？

いいえ。サブスクリプションの決済手段を追加、置換、並べ替え、削除する**加盟店向けエンドポイントはありません**。公開されている
サブスクリプション API は `create`、`inquiry`、`cancel`、`manage`、`change`、`change/inquiry`、`update` であり、
いずれも紐づく決済手段の一覧には触れません。

自社プロダクトからできること：

* `/api/v1/subscription/inquiry` から紐づく決済手段と `canChangePaymentMethod` フラグを読み取り、独自のビューを表示する。
* 実際の変更を行うために、顧客をホスト型ページへ送る。
* 異なる `paymentInfo` で**プラン変更**を行い、チェックアウトで再承認させることで、顧客を別の決済手段へ移す。
  [サブスクリプションのプラン変更](/docs/ja/support/subscription-plan-change-faq) を参照してください。

つまり、機能するパターンはこうです。お客様の UI が状態を表示し、ホスト型ページが変更を実行します。

## ページでのキャンセルは即時ですか、それとも期間終了時ですか？

**即時です。** 顧客が確認すると、サブスクリプションは `USER_CANCELLED` に移り、以降の課金期間は開かれません。
ページには期間終了時のオプションはなく、`/api/v1/subscription/cancel` も即時です。

これははっきり述べておく価値があります。加盟店自身のプロダクトルールとの最もよくある不一致だからです。Waffo がキャンセルするのは
**課金**であり、**利用権**ではありません。「支払済み期間が終わるまでサービスを維持する」というポリシーであれば、お客様側で実装します。

1. サブスクリプションのステータス通知を監視します。
2. キャンセル時、顧客がすでに支払った期間の終了までアクセスを維持します。その日付は、キャンセル前の `nextPaymentDateTime`、
   または課金履歴上の現在の期間の終了日から分かります。
3. その時点でアクセスを取り消します。

Waffo が期間終了時の廃止を行う唯一の場所は、**将来の `startTime` を持つプラン変更**です。これは古いプランを現在の期間の終了まで
稼働させてから廃止します。本当の要件が「サイクル終了時にダウングレードする」ことであれば、キャンセルではなくこれが
そのための仕組みです。

## 顧客がページでキャンセルすると、どのステータス変更と Webhook を受け取りますか？

サブスクリプションは `USER_CANCELLED` に移り、そのステータスを持つ**サブスクリプションステータス通知**を受信します。
「ホスト型ページでキャンセルされた」という別のイベントはありません。

自社レコードではなく、その Webhook をトリガーとして扱ってください。このキャンセルを開始したのはお客様ではないため、
通知を処理するまでお客様側はサブスクリプションがまだ有効だと認識しています。`USER_CANCELLED` と `MERCHANT_CANCELLED` の違いが、
顧客起点の離脱とお客様が実行したものを見分ける方法です。

すでに回収されたお金はキャンセルによって変わりません。現在の期間分を顧客に返したい場合は、その期間の課金を返金してください。
[返金](/docs/ja/support/refund-faq) を参照してください。

## ページはどこまでブランディングできますか？

ページは、**サブスクリプションに設定されたチェックアウトの外観とロゴ** — チェックアウトで使用しているのと同じ
`cashierAppearance` とブランド設定 — を引き継ぎます。そのため、顧客がブランドのないページに着地するのではなく、
色、タイポグラフィ、ロゴが反映されます。

設定でき**ない**もの：

| | |
| - | - |
| 色、背景、タイポグラフィ、ロゴ | チェックアウトの外観から適用される |
| ページの文言とラベル | 固定。加盟店は編集できない。 |
| キャンセルボタンやその他のコントロールの非表示 | 非対応 |
| 独自のフィールドやセクションの追加 | 非対応 |

したがって、「顧客がここでキャンセルできてはならない」という要件がある場合、答えはページを設定することではありません。
顧客をそこへ送らないこと、そして Waffo のメールを自社の管理 URL に向けることです。

## ページはどの言語で表示されますか？

Waffo がサブスクリプションのチェックアウトとメールに使用するのと同じ解決方法です。

1. サブスクリプションにチェックアウト言語を設定していれば、その言語。
2. そうでなければ、サブスクリプションの課金通貨から導出。
3. フォールバックとして英語。

言語はリンク発行時点で埋め込まれるため、チェックアウト言語を設定する前に発行したリンクは、新しいリンクを発行するまで
古い言語のままです。顧客の言語が課金通貨と一致しない場合は、導出に頼らず、サブスクリプションにチェックアウト言語を
明示的に設定してください。

プランのタイトルと説明は**お客様の**文字列です。ページはサブスクリプションで送信した説明をそのまま表示するため、
ページ自体のロケールに関係なく、お客様が書いた言語で表示されます。プラン名をローカライズしている場合は、
サブスクリプション作成時にローカライズ済みの文字列を送信してください。


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