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

# サブスクリプション

> 自動化された継続収益

## 継続収益を自動化。

顧客がサブスクリプションを開始したら、請求サイクル、失敗した支払い、ライフサイクル管理は私たちが処理します。あなたは製品に集中してください。

***

## 仕組み

```
顧客がサブスクリプション → 請求サイクル → 自動引き落とし → 繰り返し
```

支払い失敗の場合、サブスクリプションは支払い状況が解決されるまで `past_due` ステータスに移行します。

***

## サブスクリプションステータス

| ステータス       | 説明                          |
| ----------- | --------------------------- |
| `pending`   | 初回支払い待ち                     |
| `active`    | 正常稼働中、通常課金                  |
| `trialing`  | 無料トライアル期間                   |
| `past_due`  | 支払い失敗、解決待ち                  |
| `canceling` | キャンセルリクエスト済み、現在の期間終了までアクティブ |
| `canceled`  | 現在の期間終了後に更新なし               |
| `expired`   | サブスクリプション期限切れ               |
| `closed`    | 未アクティブ — 支払いタイムアウト          |

***

## 請求サイクル

| サイクル | 頻度     | 最適な用途      |
| ---- | ------ | ---------- |
| 週次   | 7日ごと   | 高使用量製品     |
| 月次   | 毎月     | 標準 SaaS    |
| 四半期  | 3ヶ月ごと  | B2B ソフトウェア |
| 年次   | 12ヶ月ごと | 長期顧客       |

***

## 無料トライアル

登録のハードルを下げ、購入前に顧客にお試しいただけます。

### トライアルの設定

サブスクリプション製品を作成する際、ダッシュボードでトライアルトグルを有効にし、日数を設定してください。

### プラットフォームレベルのトライアル保護

Waffo Pancake は記録販売者（MOR）として、トライアルの不正利用を自動的に防止します：

| レイヤー                  | 仕組み                                                                   |
| --------------------- | --------------------------------------------------------------------- |
| **プラットフォーム（Pancake）** | すべてのマーチャントにわたって各消費者のトライアル履歴を追跡し、新しいサブスクリプションごとに利用可能な最大トライアル日数を計算します。  |
| **マーチャント**            | API でオーダーを作成する際に `requested_trial_days` を渡して、顧客ごとにトライアル期間をカスタマイズできます。 |

**2つのレイヤーの相互作用：**

* マーチャントのリクエストがプラットフォーム最大値以下の場合 → マーチャントのリクエスト値が使用されます
* マーチャントのリクエストがプラットフォーム最大値を超える場合 → プラットフォーム最大値にフォールバックします
* マーチャントが指定しない場合 → プラットフォーム最大値がそのまま使用されます

### 購入者ID とトライアル保護

トライアル適格性は `buyerIdentity` で追跡されます — [認証済みチェックアウト](/ja/integrate/sdks#チェックアウトモード)で提供する安定した識別子です。プラットフォームはこれを使用して、セッション間での重複トライアル取得を検出します。

<Warning>
  `buyerIdentity` なし（匿名チェックアウト）の場合、トライアル適格性チェックは完全にスキップされます。購入者はメールアドレスを変更するだけで無制限にトライアルを取得できます。
</Warning>

### プロダクトグループの共有トライアル

サブスクリプション製品が `sharedTrial: true` の**プロダクトグループ**にまとめられている場合、トライアルの利用状況はグループ内のすべての製品で共有されます。消費者がグループ内のいずれかの製品でトライアルを使用済みの場合、同じグループ内の別の製品で新たなトライアルを開始することはできません。

<Tip>
  7〜14日間のトライアルが最も効果的です。短すぎると評価する時間が足りず、長すぎると忘れられてしまいます。
</Tip>

***

## 失敗した支払い

支払いが失敗すると、サブスクリプションは `past_due` ステータスに移行します。顧客には支払い方法の更新を促すメールが送信されます。

***

## サブスクリプション管理

### キャンセル

キャンセル時、サブスクリプションはまず `canceling` の中間ステータスに移行し、現在の請求期間が終了すると自動的に `canceled` に変わります。顧客はその間アクセスを維持します。

```bash theme={"system"}
POST /v1/actions/subscription-order/cancel-order
{
  "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz"
}
```

レスポンスは `canceling` ステータスを返し、サブスクリプションが現在の期間終了後に正式にキャンセルされることを示します。

<Note>
  即時キャンセルのオプションはありません。顧客は常に支払い済み期間の終了までアクセスを維持します。ステータスの流れ：`active` → `canceling` → `canceled`。
</Note>

### アップグレード/ダウングレード

| シナリオ        | 動作             |
| ----------- | -------------- |
| 期間中のアップグレード | 即座に適用          |
| 期間中のダウングレード | 現在の請求期間の終了時に適用 |

```bash theme={"system"}
POST /v1/actions/subscription-order/change-product
{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "targetProductId": "target-product-uuid"
}
```

<Warning>
  このエンドポイントはまだ実装されていません（501 を返します）。将来のリリースで利用可能になります。
</Warning>

***

## メトリクス

### MRR（月次経常収益）

```
週次サブスク：    $10 x 4.33 = $43.30 MRR
月次サブスク：    $29 x 1 = $29 MRR
年次サブスク：    $290 / 12 = $24.17 MRR
```

### 主要メトリクス

| メトリクス | 意味          |
| ----- | ----------- |
| MRR   | 月次経常収益      |
| Churn | キャンセルした割合   |
| LTV   | 顧客生涯価値      |
| ARPU  | ユーザーあたり平均収益 |

***

## Webhooks

サブスクリプションのライフサイクルイベントを Webhook で受信できます。**設定 --> Webhooks** で Webhook エンドポイントを設定してください。

<Warning>
  具体的な Webhook イベント名は変更される可能性があるため、ここでは記載していません。利用可能なイベントの最新リストについては、ダッシュボードの Webhook 設定をご参照ください。
</Warning>

Webhook ペイロードは Waffo Pancake の標準的な規約に従います：

* ID は UUID v4 形式
* 金額は表示形式の文字列
* タイムスタンプは ISO 8601 UTC
* 請求頻度は `billingPeriod` フィールドを使用（例：`monthly`、`yearly`）

***

## カスタマーポータル

顧客がセルフサービスでサブスクリプションを管理：

* 詳細を確認
* 支払い方法を更新
* プランを変更
* キャンセル
* 請求書をダウンロード

<Card title="カスタマーポータル" icon="user" href="/ja/features/customer-portal">
  セルフサービスのサブスクリプション管理。
</Card>

***

## ベストプラクティス

<AccordionGroup>
  <Accordion title="年間割引を提供">
    年額で 15-20% オフ = 解約率低下 + キャッシュフロー改善。
  </Accordion>

  <Accordion title="即座にアクセスを遮断しない">
    支払い失敗 ≠ 即時キャンセル。顧客にカード更新の時間を与える。
  </Accordion>

  <Accordion title="リマインダーを送信">
    試用期間終了前、請求前に通知。顧客を驚かせない。
  </Accordion>
</AccordionGroup>