ReferenceAPI reference
Billing
18 operations in the Billing group.
9 of 18 operations on this page are generated contract stubs: the routes are real, the schemas are placeholders pending the owning subsystem's contract pass.
POST /api/billing/checkout-session
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: postApiBillingCheckoutSession
Request body — application/json · object
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 201 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
POST /api/billing/customer/reconcile
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: postApiBillingCustomerReconcile
Request body — application/json · object
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 201 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/billing/invoices
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiBillingInvoices
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
POST /api/billing/invoices/{invoiceId}/reconcile
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: postApiBillingInvoicesInvoiceIdReconcile
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
invoiceId | path | yes | string |
Request body — application/json · object
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 201 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/billing/payment-method
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiBillingPaymentMethod
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
POST /api/billing/portal-session
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: postApiBillingPortalSession
Request body — application/json · object
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 201 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/billing/pricing
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiBillingPricing
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/billing/summary
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiBillingSummary
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
GET /api/billing/webhooks
Generated contract stub — the route is real and served, but its request/response schema has not been hand-tightened yet.
Operation ID: getApiBillingWebhooks
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response | GenericApiResponse |
| 401 | Authentication is required | ErrorEnvelope |
| 403 | Permission denied | ErrorEnvelope |
| 422 | Validation failed | ErrorEnvelope |
| 500 | Server error | ErrorEnvelope |
POST /api/resources/{workspace}/billing/checkout-session
Operation ID: createBillingCheckoutSession
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Request body — application/json · BillingCheckoutSessionRequest
| Field | Type | Required |
|---|---|---|
success_url | string | no |
cancel_url | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Creates a Stripe Checkout redirect for workspace billing setup. Stripe customer, session, subscription, and payment data are never returned. | BillingCheckoutSessionResponse |
POST /api/resources/{workspace}/billing/customer/reconcile
Operation ID: reconcileBillingCustomer
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Workspace-scoped customer/subscription drift repair. The workspace customer reference is read from existing usage reports before any Stripe lookup. | BillingCustomerReconciliationResponse |
GET /api/resources/{workspace}/billing/invoices
Operation ID: listBillingInvoices
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Safe billing invoice history from Stripe usage reports. | BillingInvoiceCollectionResponse |
POST /api/resources/{workspace}/billing/invoices/{invoiceId}/reconcile
Operation ID: reconcileBillingInvoice
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
invoiceId | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Workspace-scoped invoice drift repair. The workspace invoice report is checked before any Stripe lookup. | BillingInvoiceReconciliationResponse |
GET /api/resources/{workspace}/billing/payment-method
Operation ID: getBillingPaymentMethod
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Safe payment method posture. Only card brand and last four are ever returned. | BillingPaymentMethodResponse |
POST /api/resources/{workspace}/billing/portal-session
Operation ID: createBillingPortalSession
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Request body — application/json · BillingPortalSessionRequest
| Field | Type | Required |
|---|---|---|
return_url | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Creates a Stripe Billing Portal redirect for a workspace-owned customer. Stripe customer, portal session, and payment data are never returned. | BillingPortalSessionResponse |
| 404 | No Stripe customer has been reconciled for this workspace yet. | BillingPortalSessionResponse |
GET /api/resources/{workspace}/billing/pricing
Operation ID: getBillingPricingCatalog
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Backend-owned billing mode, billable unit, and pass-through admission catalog. Does not expose Stripe price ids, meter event names, or secrets. | BillingPricingCatalogResponse |
GET /api/resources/{workspace}/billing/summary
Operation ID: getBillingSummary
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
period_start | query | no | string | |
period_end | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Billing summary for the current usage period. | BillingSummaryResponse |
GET /api/resources/{workspace}/billing/webhooks
Operation ID: getStripeWebhookStatus
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Stripe webhook configuration and dedupe status for billing operations. | StripeWebhookStatusResponse |