サブスクリプション

AMはアカウントのStripeサブスクリプションのライフサイクルを管理し、価格設定とアクセス制御に集中できるようにします。

チェックアウトセッションを作成し、顧客がプランを管理できるようにし、Stripeとアカウントのアクセス状態を同期します。

サブスクリプションフロー

エンドポイント

Endpoint	目的
`POST /api/accounts/:account_id/subscriptions/stripe/checkout-session`	サブスクリプションのチェックアウト開始
`POST /api/accounts/:account_id/subscriptions/stripe/portal-session`	カスタマーポータルを開く
`POST /api/accounts/:account_id/subscriptions/stripe/checkout-session-sync`	チェックアウトとサブスクの同期
`POST /api/accounts/:account_id/subscriptions/sync`	Stripeからサブスクを同期
`POST /api/accounts/:account_id/subscriptions/change`	プラン/価格を変更
`POST /api/accounts/:account_id/subscriptions/cancel`	サブスクリプションを解約
`GET /api/accounts/:account_id/subscriptions`	サブスクリプション一覧
`GET /api/accounts/:account_id/subscriptions/features`	有効な機能一覧
`GET /api/accounts/:account_id/subscriptions/identity`	Stripe顧客IDの取得
`POST /api/applications/:application_id/subscriptions/stripe/webhook`	Stripe Webhook

チェックアウトセッション

新規サブスクリプションのStripe Checkoutセッションを作成します。

// Request
{
  price_id: "price_...",
  success_url: "https://app.example.com/success",
  cancel_url: "https://app.example.com/cancel"
}

// Response
{
  url: "https://checkout.stripe.com/..."
}

返却されたURLへユーザーをリダイレクトします。支払い後、Stripeが成功URLへリダイレクトします。

カスタマーポータル

顧客が以下を自己管理できます。

支払い方法の更新
請求書の確認
サブスクリプションの解約
プラン変更

// Request
{
  return_url: "https://app.example.com/settings";
}

// Response
{
  url: "https://billing.stripe.com/...";
}

サブスクリプションID

各アカウントにはStripe顧客に紐づくサブスクリプションIDがあります。Webhookの解決や課金状態の同期に使用します。

Webhookイベント

AMはStripeのWebhookを処理し、失敗時はリトライします。

イベント	アクション
`checkout.session.completed`	顧客を紐づけてサブスクを作成
`customer.subscription.*`	サブスクリプションデータを同期
`invoice.paid`	請求書同期 + アクセス更新
`invoice.payment_failed`	アクセス期限の更新