Billing
Stripe Checkout and customer-portal links.
Get a Checkout link
POST /v1/billing/checkout
Credential: Secret key (Authorization: Bearer spk_live_…)
Returns a Stripe Checkout URL for Pro, or a customer-portal URL (kind: portal) when already subscribed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | The first response is stored 24 h per (account, key) and replayed verbatim. Same key with a different body → 409 idempotency_conflict. 1–64 chars. |
Request body
application/json (optional)
| Field | Type | Description |
|---|---|---|
plan | string | One of pro. Default pro. |
Responses
200 Link.
| Field | Type | Description |
|---|---|---|
kind required | string | portal when the account already has an active, trialing or past-due subscription. One of checkout, portal. |
url required | string | Format uri. |
expires_at | string | null | Format date-time. |
| Status | Error codes |
|---|---|
| 400 | invalid_json, validation_failed (see details), invalid_request. |
| 401 | missing_credentials, invalid_credentials, not_signed_in (/v1/web/*). |
| 403 | wrong_credential_type, secret_key_in_browser, csrf_failed, recent_auth_required, session_full, nickname_rejected. |
| 409 | session_ended, idempotency_conflict (same key, different body; or, retryable, the first request with that key is still in progress — retry the same request in a few seconds). |
| 429 | rate_limited, with retry_after_s. |
| 500 | internal_error. |
| 503 | no_live_capacity or service_unavailable, with retry_after_s and Retry-After. Billing endpoints return service_unavailable when billing is not configured in the environment or Stripe is unreachable. |
Get a customer-portal link
POST /v1/billing/portal
Credential: Secret key (Authorization: Bearer spk_live_…)
Manage card, cancel, invoices. A portal link is returned even when the account has no
Stripe customer yet: one is created first. Billing unconfigured in the environment or
Stripe unreachable → 503 service_unavailable with Retry-After.
Responses
200 Link.
| Field | Type | Description |
|---|---|---|
url required | string | Format uri. |
| Status | Error codes |
|---|---|
| 401 | missing_credentials, invalid_credentials, not_signed_in (/v1/web/*). |
| 403 | wrong_credential_type, secret_key_in_browser, csrf_failed, recent_auth_required, session_full, nickname_rejected. |
| 429 | rate_limited, with retry_after_s. |
| 500 | internal_error. |
| 503 | no_live_capacity or service_unavailable, with retry_after_s and Retry-After. Billing endpoints return service_unavailable when billing is not configured in the environment or Stripe is unreachable. |