Billing
5 operations.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/billing/plans | Get available subscription plans |
| POST | /api/v1/organizations/{organizationIdOrSlug}/billing/checkout | Create checkout session |
| POST | /api/v1/organizations/{organizationIdOrSlug}/billing/portal | Create customer portal session |
| GET | /api/v1/organizations/{organizationIdOrSlug}/billing/subscription | Get organization subscription |
| GET | /api/v1/organizations/{organizationIdOrSlug}/billing/usage | Get organization billing usage |
Get available subscription plans
GET/api/v1/billing/plans
Retrieve all available subscription plans.
Authentication
- Requires an authenticated caller with the billing:read operation
Response
- Returns a provider-neutral list of all active subscription plans
- Plans are sorted by price (lowest first)
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | The request is malformed or cannot be processed. | application/json PublicApiError
|
| 401 | Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Create checkout session
POST/api/v1/organizations/{organizationIdOrSlug}/billing/checkout
Create a Stripe checkout session for subscription purchase.
Authentication
- Requires the authenticated user to have billing:manage permission
- Public API requests use Bearer authentication; Studio uses session authentication
Request
- planKey: The subscription plan key to purchase
- successUrl: URL to redirect to on successful checkout
- cancelUrl: URL to redirect to if checkout is cancelled
- csrfToken: Required for Studio session requests; omitted for API key requests
- Idempotency-Key: Printable retry key, scoped to this Organization and user
Response
- Returns a checkout URL to redirect the user to Stripe
- Return URLs must be exact Studio billing or pricing destinations
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| organizationIdOrSlug | string | required | Identifies the organization by its stable identifier or slug. Applies to Create checkout session. |
header
| Name | Type | Required | Description |
|---|---|---|---|
| Idempotency-Key | string | required |
Request body
required — Request body for: Create checkout session.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
| planKey | string | required | |
| successUrl | string | required | |
| cancelUrl | string | required | |
| csrfToken | string | optional | Required for Studio session authentication; not required for Bearer API keys. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Response for status 400 | application/json PublicApiError
|
| 401 | Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Resource not found. | application/json PublicApiError
|
| 422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json PublicApiError
|
| 429 | Rate limited by an upstream dependency. Retry after the Retry-After interval. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
| 503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json PublicApiError
|
Create customer portal session
POST/api/v1/organizations/{organizationIdOrSlug}/billing/portal
Create a Stripe customer portal session for subscription management.
Authentication
- Requires the authenticated user to have billing:manage permission
- Public API requests use Bearer authentication; Studio uses session authentication
Request
- returnUrl: URL to redirect to when leaving the portal
- csrfToken: Required for Studio session requests; omitted for API key requests
- Idempotency-Key: Printable retry key, scoped to this Organization and user
Response
- Returns a portal URL to redirect the user to Stripe
- returnUrl must be an exact Studio billing or pricing destination
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| organizationIdOrSlug | string | required | Identifies the organization by its stable identifier or slug. Applies to Create customer portal session. |
header
| Name | Type | Required | Description |
|---|---|---|---|
| Idempotency-Key | string | required |
Request body
required — Request body for: Create customer portal session.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
| returnUrl | string | required | |
| csrfToken | string | optional | Required for Studio session authentication; not required for Bearer API keys. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Response for status 400 | application/json PublicApiError
|
| 401 | Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Resource not found. | application/json PublicApiError
|
| 422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json PublicApiError
|
| 429 | Rate limited by an upstream dependency. Retry after the Retry-After interval. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
| 503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json PublicApiError
|
Get organization subscription
GET/api/v1/organizations/{organizationIdOrSlug}/billing/subscription
Retrieve the provider-neutral subscription projection for the addressed Organization.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| organizationIdOrSlug | string | required | Identifies the organization by its stable identifier or slug. Applies to Get organization subscription. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | The request is malformed or cannot be processed. | application/json PublicApiError
|
| 401 | Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Resource not found. | application/json PublicApiError
|
| 422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Get organization billing usage
GET/api/v1/organizations/{organizationIdOrSlug}/billing/usage
Retrieve bounded usage counters for the addressed Organization billing period.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| organizationIdOrSlug | string | required | Identifies the organization by its stable identifier or slug. Applies to Get organization billing usage. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | The request is malformed or cannot be processed. | application/json PublicApiError
|
| 401 | Authentication failed. Possible reasons: - Authorization header is not provided - Invalid API key - Session expired | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Resource not found. | application/json PublicApiError
|
| 422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|