billing
결제 카테고리의 API 작업 6개를 다룹니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
| POST | /v1/hooks/polar | Polar 결제 웹훅 |
| GET | /v1/orgs/{orgSlug}/billing | org의 플랜 및 결제 상태 |
| POST | /v1/orgs/{orgSlug}/billing/checkout | Pro 요금제용 체크아웃 세션을 생성합니다 |
| 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 세 헤더와 서버의 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는 두 플랜의 제한 테이블입니다. viewer 이상의 권한이 필요합니다.
operationId getBilling
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 결제 상태 | BillingStatus |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/billing/checkout
단일 Polar 결제 세션을 생성하고 해당 url을 반환합니다. 대시보드는 이 URL을 자체 페이지의 iframe에 표시합니다(세션의 embed_origin은 returnTo의 출처입니다). 결제를 완료해도 그 자체로 플랜이 변경되지는 않습니다. 플랜은 Polar의 웹훅이 도착해야 변경되며, 화면은 성공 이벤트 이후 상태를 다시 읽어옵니다.
returnTo는 이 배포의 공개 URL 하위여야 하며, 그렇지 않으면 400이 반환됩니다. org가 이미 Pro인 경우 409 already_pro가 반환되므로 대신 결제 포털을 여세요. admin 권한이 필요합니다.
operationId createBillingCheckout
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 체크아웃 세션 | object |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 409 | already_pro | Error |
| 501 | billing_off — 결제가 설정되어 있지 않습니다 | — |
| 502 | billing_unavailable — Polar가 응답하지 않습니다 | — |
POST /v1/orgs/{orgSlug}/billing/portal
Polar 고객 포털의 1회용 url을 반환합니다. 결제 수단, 영수증, 해지가 모두 그곳에서 처리되므로 카드 정보는 runlot에 전달되지 않습니다. 결제한 적이 없는 org는 404를 반환합니다. admin 권한이 필요합니다.
operationId createBillingPortal
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 포털 세션 | object |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 501 | billing_off | — |
| 502 | billing_unavailable | — |
POST /v1/orgs/{orgSlug}/billing/session
결제 수단 임베드에 필요한 고객 세션 토큰을 반환합니다. 이 토큰은 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 | — |