billing
billing カテゴリの API 操作を6件カバーします。
| メソッド | パス | 説明 |
|---|---|---|
| POST | /v1/hooks/polar | Polar の billing webhook(docs/billing.md) |
| GET | /v1/orgs/{orgSlug}/billing | org のプランと billing ステータス(docs/billing.md) |
| 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を返し、無視されます)。
orgs.plan を変更する唯一の場所です: 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)と現在の期間の終了日(periodEnd)も返します。enabled が false の場合、このデプロイでは billing が設定されていません — 画面には連絡先アドレスのみが表示されます。sandbox が true の場合、これは Polar のテスト環境であり、実際の billing はありません。
limits は2つのプランの上限テーブルです(cp/internal/plan)。画面に数値が表示されない理由は OrgMembership.projectLimit と同じです。Viewer 以上です。
operationId getBilling
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | Billing ステータス | BillingStatus |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/billing/checkout
単一の Polar checkout セッションを作成し、その url を返します。ダッシュボードはその URL を専用ページの iframeに表示します(@polar-sh/checkout;セッションの embed_origin は returnTo の origin です)。支払いが完了しても、プランは変更されません — プランを変更するのは webhook(/v1/hooks/polar)です。画面は成功イベントの後に状態を再読み込みします。
returnTo はサーバーの RUNLOT_PUBLIC_URL の下にある必要があります(そうでない場合は400)。すでに Pro の場合は409 already_pro です — 代わりにポータルを開いてください。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 を返します。支払い方法の変更、レシート、キャンセルはすべてそこで行われます — そのフォームを自社の画面には置きません(カード番号を自社サーバーに置かないことが MoR の価値です)。一度も支払いをしていない 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
@polar-sh/checkout の支払い方法埋め込みに必要なカスタマーセッショントークンです。有効期間はそのカスタマー1件につき1時間です。画面を開くたびに新たに取得します。billing 履歴のない org は404になります。admin です。
operationId createBillingSession
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | カスタマーセッション | object |
| 403 | — | — |
| 404 | — | — |
| 501 | billing_off | — |
| 502 | billing_unavailable | — |
POST /v1/orgs/{orgSlug}/billing/cancel
cancel: true の場合、Pro は現在の期間の終了時に終了します(それまでは Pro のまま)— Polar の cancel_at_period_end です。false は予定されたキャンセルを取り消します。即時の失効はありません。すでに支払い済みの期間は最後まで使用されます。レスポンスは即座にこちらの行の status を更新し、webhook も間もなく同じ結論に達します。Pro でない場合は 409 not_pro です。admin。
operationId cancelBilling
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 変更されたステータス | object |
| 403 | — | — |
| 404 | — | — |
| 409 | not_pro | Error |
| 501 | billing_off | — |
| 502 | billing_unavailable | — |