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` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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 may point to your own UI; use absolute HTTP or HTTPS URLs without embedded credentials

Parameters

path

Name	Type	Required	Description
`organizationIdOrSlug`	`one of 2 types`	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` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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 may point to your own UI; use an absolute HTTP or HTTPS URL without embedded credentials

Parameters

path

Name	Type	Required	Description
`organizationIdOrSlug`	`one of 2 types`	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` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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`	`one of 2 types`	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` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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`	`one of 2 types`	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` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)