billing
billing カテゴリの API 操作 6 件を説明します。
| メソッド | パス | 説明 |
|---|---|---|
| POST | /v1/hooks/polar | Polar 課金 Webhook |
| GET | /v1/orgs/{orgSlug}/billing | Org のプランと課金状況 |
| POST | /v1/orgs/{orgSlug}/billing/checkout | Pro プランの checkout セッションを作成します |
| POST | /v1/orgs/{orgSlug}/billing/portal | カスタマーポータルセッションを作成します(支払い方法・レシート・キャンセル) |
| POST | /v1/orgs/{orgSlug}/billing/session | カスタマーセッショントークン(支払い方法の埋め込みを認証します) |
| POST | /v1/orgs/{orgSlug}/billing/cancel | 期間終了時のキャンセルを予約または取り消します |
POST /v1/hooks/polar
これは呼び出すパスではありません。Polar がここにサブスクリプションイベントを配信します。認証はトークンではなくStandard Webhooks 署名によって行われます。webhook-id、webhook-timestamp、webhook-signature の3つのヘッダーと、サーバーの RUNLOT_POLAR_WEBHOOK_SECRET を用いて検証されます（一致しない場合は403、タイムスタンプは±5分以内である必要があります）。同じ webhook-id は一度しか適用されません（再配信は200を返し、無視されます）。
これは組織のプランを移動させる仕組みです。subscription.active と updated の場合、ステータスが active／trialing／past_due であれば Pro に、それ以外（canceled、unpaid など）はすべて Free に対応します。サーバーにトークンがない場合は501を返します。クライアントライブラリからはこれを呼び出しません。
operationId polarHook
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 受信済み（applied が true の場合、プランが変更されています） | — |
| 400 | — | — |
| 403 | 署名が一致しません | — |
| 501 | 課金がオフです | — |
GET /v1/orgs/{orgSlug}/billing
プラン（plan）と、Pro の場合はそのステータス（status：active・past_due・canceled・granted）、現在の期間の終了日（periodEnd）を返します。granted はサブスクリプションなしで Runlot から提供される Pro です。課金は発生せず、含まれる利用量を超えた分も含まれます。enabled が false の場合、このデプロイでは課金が設定されておらず、画面には連絡先のみが表示されます。sandbox が true の場合はテスト環境であるため、実際の課金は発生しません。
limits は2つのプランの上限テーブルです。viewer 以上が必要です。
operationId getBilling
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | Billing ステータス | BillingStatus |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/billing/checkout
単一の Polar チェックアウトセッションを作成し、その url を返します。ダッシュボードはその URL を専用ページの iframe に表示します（セッションの embed_origin は returnTo のオリジンです）。決済の完了だけではプランは変更されません。プランは Polar の webhook が届いた時点で変更され、画面は成功イベントの後に状態を再読み込みします。
returnTo はこのデプロイの公開 URL 配下である必要があり、そうでない場合は 400 になります。org がすでに Pro の場合は 409 already_pro になります — 代わりに billing ポータルを開いてください。admin が必要です。
operationId createBillingCheckout
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | Checkout セッション | object |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 409 | already_pro | Error |
| 501 | billing_off — 課金が設定されていません | — |
| 502 | billing_unavailable — Polar が応答していません | — |
POST /v1/orgs/{orgSlug}/billing/portal
Polar のカスタマーポータル用のワンタイム url を返します。支払い方法・領収書・解約はすべてそこで処理されるため、カード情報が runlot に届くことはありません。一度も支払いをしたことがない org では 404 になります。admin が必要です。
operationId createBillingPortal
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | Portal セッション | object |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 501 | billing_off | — |
| 502 | billing_unavailable | — |
POST /v1/orgs/{orgSlug}/billing/session
支払い方法の埋め込みに必要なカスタマーセッショントークンを返します。有効期限は1時間で、その1件の顧客のみ有効なため、画面を開くたびに新しく取得してください。課金履歴のない org では 404 になります。admin が必要です。
operationId createBillingSession
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | カスタマーセッション | object |
| 403 | — | — |
| 404 | — | — |
| 501 | billing_off | — |
| 502 | billing_unavailable | — |
POST /v1/orgs/{orgSlug}/billing/cancel
cancel: true にすると、Pro は現在の期間の終了時に終了し、それまでは有効なままです。false にすると、予約された解約が取り消されます。即時の失効はなく、すでに支払い済みの期間はすべて利用できます。レスポンスには新しい status が即座に反映されます。org が Pro でない場合は 409 not_pro になります。admin が必要です。
operationId cancelBilling
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 変更されたステータス | object |
| 403 | — | — |
| 404 | — | — |
| 409 | not_pro | Error |
| 501 | billing_off | — |
| 502 | billing_unavailable | — |