Billing API

Billing API for Scalix Cloud: plans and pricing, hosted checkout and portal, subscriptions, invoices, payment methods, credits and the credit ledger, spending cap, usage analytics and forecast, tax info and calculation, GDPR data-subject ops, and service/module/infra agreements. Tenant identity is resolved server-side from the caller's credential.

REST API endpoints for Billing. 60 operations.

Get the service catalog

plaintext

GET /v1/billing/catalog/{tenant_id}

The billable-service catalog with per-service agreement state for the org.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Service catalog with agreement state
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getServiceCatalog

Start a hosted checkout

plaintext

POST /v1/billing/checkout

Creates a provider checkout session for the plan upgrade (or first paid plan) and returns the URL to send the customer to.

Auth: Bearer API key

Request body

application/json (required) — schema CheckoutRequest.

Responses

Status	Description
`201`	Checkout session created
`400`	Invalid request (e.g. missing tenant/email, or the free plan)
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: createCheckout

Get the credit ledger

plaintext

GET /v1/billing/credit-ledger/{tenant_id}

Returns the org's full credit ledger (the BillingPage's ledger table).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Credit ledger
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getCreditLedger

Get credit transactions

plaintext

GET /v1/billing/credit-transactions/{tenant_id}

Returns the org's credit transaction list (the BillingPage's transactions table).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Credit transactions
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getCreditTransactions

Get per-metric usage cost

plaintext

GET /v1/billing/credit-usage-metrics/{tenant_id}

Returns credit consumption broken down by billing metric (the usage-by-service view).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Usage cost by metric
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getUsageCostByMetric

Get credit usage

plaintext

GET /v1/billing/credit-usage/{tenant_id}

Returns the org's credit consumption for the current period.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Credit usage for the period
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getCreditUsage

Get the credit balance

plaintext

GET /v1/billing/credits/{tenant_id}

Returns the org's current credit balance and billing mode (legacy vs credit).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Credit balance and billing mode
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getCreditBalance

Start a credit top-up checkout

plaintext

POST /v1/billing/credits/{tenant_id}/checkout

Creates a hosted checkout session to buy credits.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Request body

application/json (required) — schema object.

Responses

Status	Description
`201`	Top-up checkout session
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: createCreditTopupCheckout

Get the credit history

plaintext

GET /v1/billing/credits/{tenant_id}/history

Returns the org's credit ledger entries (grants, purchases, deductions).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Credit ledger entries
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getCreditHistory

Create a Razorpay top-up order

plaintext

POST /v1/billing/credits/{tenant_id}/razorpay-order

Razorpay-only path: creates the order the console's Checkout.js modal pays against.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Request body

application/json (required) — schema object.

Responses

Status	Description
`201`	Razorpay order
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: createRazorpayTopupOrder

Submit cancellation feedback

plaintext

POST /v1/billing/feedback/cancellation

Records why an org cancelled; feeds churn analysis. The caller's credential must match the tenant_id in the body.

Auth: Bearer API key

Request body

application/json (required) — schema object.

Responses

Status	Description
`200`	Feedback recorded
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: submitCancellationFeedback

Get the org's GDPR consent state

plaintext

GET /v1/billing/gdpr/{tenant_id}/consent

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Consent state
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getGdprConsent

Update the org's GDPR consent

plaintext

POST /v1/billing/gdpr/{tenant_id}/consent

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Request body

application/json (required) — schema object.

Responses

Status	Description
`200`	Consent updated
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: updateGdprConsent

Correct the org's billing data (GDPR data-subject correction)

plaintext

POST /v1/billing/gdpr/{tenant_id}/correct

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Request body

application/json (required) — schema object.

Responses

Status	Description
`200`	Billing data corrected
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: gdprCorrect

Delete the org's billing data (GDPR data-subject deletion)

plaintext

POST /v1/billing/gdpr/{tenant_id}/delete

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Billing data deleted
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: gdprDelete

Export the org's billing data (GDPR data-subject export)

plaintext

POST /v1/billing/gdpr/{tenant_id}/export

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Billing data export
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: gdprExport

Get the glitch-tracker status

plaintext

GET /v1/billing/glitch-tracker

Whether the Glitches feed is enabled for the project and its service agreement state.

Auth: Bearer API key

Responses

Status	Description
`200`	Glitch-tracker status
`401`	Missing or invalid API key
`500`	Internal error

operationId: getGlitchTrackerStatus

Disable the glitch-tracker

plaintext

POST /v1/billing/glitch-tracker/disable

Auth: Bearer API key

Responses

Status	Description
`200`	Glitch-tracker disabled
`401`	Missing or invalid API key
`500`	Internal error

operationId: disableGlitchTracker

Enable the glitch-tracker

plaintext

POST /v1/billing/glitch-tracker/enable

Auth: Bearer API key

Responses

Status	Description
`200`	Glitch-tracker enabled
`401`	Missing or invalid API key
`500`	Internal error

operationId: enableGlitchTracker

Get the infrastructure agreement

plaintext

GET /v1/billing/infra-agreement/{tenant_id}

The org's infrastructure services agreement (the BillingPage's agreements tab).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Infrastructure agreement
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getInfraAgreement

Disable the infrastructure agreement

plaintext

POST /v1/billing/infra-agreement/{tenant_id}/disable

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Infrastructure agreement disabled
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: disableInfraAgreement

List the org's invoices

plaintext

GET /v1/billing/invoices/{tenant_id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Invoice list
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: listInvoices

Render an invoice as HTML

plaintext

GET /v1/billing/invoices/{tenant_id}/{invoice_id}/html

Returns the printable invoice document for download/email.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`invoice_id`	path	`string`	Yes	Invoice id

Responses

Status	Description
`200`	Invoice HTML
`401`	Missing or invalid API key
`403`	Not your org
`404`	Invoice not found
`500`	Internal error

operationId: renderInvoiceHtml

Retry a failed invoice payment

plaintext

POST /v1/billing/invoices/{tenant_id}/{invoice_id}/retry

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`invoice_id`	path	`string`	Yes	Invoice id

Responses

Status	Description
`200`	Payment retried
`401`	Missing or invalid API key
`403`	Not your org
`404`	Invoice not found
`500`	Internal error

operationId: retryInvoicePayment

List model pricing tiers

plaintext

GET /v1/billing/model-tiers

Public — no API key required. The per-tier token prices used for usage-based billing.

Auth: none

Responses

Status	Description
`200`	Model pricing tiers
`500`	Internal error

operationId: listModelTiers

Get a module agreement

plaintext

GET /v1/billing/module-agreement/{tenant_id}/{module}

The agreement for one billable module (per-module autodebit setup).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`module`	path	`string`	Yes	Module id

Responses

Status	Description
`200`	Module agreement
`401`	Missing or invalid API key
`403`	Not your org
`404`	Module agreement not found
`500`	Internal error

operationId: getModuleAgreement

Set up module autodebit

plaintext

POST /v1/billing/module-agreement/{tenant_id}/{module}/autodebit

Authorizes automatic debit for the module's usage charges.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`module`	path	`string`	Yes	Module id

Responses

Status	Description
`200`	Autodebit set up
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: setupModuleAutodebit

Disable a module agreement

plaintext

POST /v1/billing/module-agreement/{tenant_id}/{module}/disable

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`module`	path	`string`	Yes	Module id

Responses

Status	Description
`200`	Module agreement disabled
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: disableModuleAgreement

Toggle overage billing

plaintext

POST /v1/billing/overage/{tenant_id}

Enables or disables allow-overage (continue serving past the credit balance and bill the difference) for the org.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Request body

application/json (required) — schema object.

Responses

Status	Description
`200`	Overage setting updated
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: toggleOverage

Get the billing overview

plaintext

GET /v1/billing/overview/{tenant_id}

The BillingPage's landing view: current plan, subscription status, balance, and spend summary in one response.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Billing overview
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getBillingOverview

List the org's payment methods

plaintext

GET /v1/billing/payment-methods/{tenant_id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Payment methods
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: listPaymentMethods

Remove a payment method

plaintext

DELETE /v1/billing/payment-methods/{tenant_id}/{pm_id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`pm_id`	path	`string`	Yes	Payment method id

Responses

Status	Description
`200`	Payment method removed
`401`	Missing or invalid API key
`403`	Not your org
`404`	Payment method not found
`500`	Internal error

operationId: removePaymentMethod

Set the default payment method

plaintext

POST /v1/billing/payment-methods/{tenant_id}/{pm_id}/default

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`pm_id`	path	`string`	Yes	Payment method id

Responses

Status	Description
`200`	Default payment method set
`401`	Missing or invalid API key
`403`	Not your org
`404`	Payment method not found
`500`	Internal error

operationId: setDefaultPaymentMethod

Authorize a Razorpay payment method

plaintext

POST /v1/billing/payment-methods/{tenant_id}/razorpay-authorization

Starts the Razorpay authorization flow for adding a card via the console's in-page Checkout.js modal.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`201`	Authorization session (razorpay_key_id + order id)
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: createRazorpayPaymentMethodAuthorization

List the billing plans (the pricing page's source)

plaintext

GET /v1/billing/plans

Public — no API key required. Returns every active plan with its prices, limits, support tier, SLA, and features.

Auth: none

Responses

Status	Description
`200`	Active plans
`500`	Internal error

operationId: listPlans

Get one plan's detail

plaintext

GET /v1/billing/plans/{plan_id}

Public — no API key required.

Auth: none

Parameters

Name	In	Type	Required	Description
`plan_id`	path	`string`	Yes	Plan id

Responses

Status	Description
`200`	Plan detail
`404`	Plan not found
`500`	Internal error

operationId: getPlanDetail

Open the billing portal

plaintext

POST /v1/billing/portal

Creates a provider customer-portal session for self-serve payment method and subscription management.

Auth: Bearer API key

Request body

application/json (required) — schema object.

Responses

Status	Description
`201`	Portal session created (url in the body)
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: createPortal

Public pricing matrix

plaintext

GET /v1/billing/pricing

Public — no API key required. The per-plan, per-provider price list the pricing page renders.

Auth: none

Responses

Status	Description
`200`	Public pricing matrix
`500`	Internal error

operationId: publicPricing

Agree to a service agreement

plaintext

POST /v1/billing/service-agreement/{tenant_id}/{service_id}/agree

Records the org's acceptance of one service's agreement (enables the service for billing).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`service_id`	path	`string`	Yes	Service id

Responses

Status	Description
`200`	Service agreement accepted
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: agreeService

Disable a service agreement

plaintext

POST /v1/billing/service-agreement/{tenant_id}/{service_id}/disable

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)
`service_id`	path	`string`	Yes	Service id

Responses

Status	Description
`200`	Service agreement disabled
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: disableServiceAgreement

List billable services

plaintext

GET /v1/billing/services

Public — no API key required. The service catalog the console's BillingPage enables per org.

Auth: none

Responses

Status	Description
`200`	Billable services
`500`	Internal error

operationId: listBillingServices

List the org's enabled services

plaintext

GET /v1/billing/services/{tenant_id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Services enabled for the org
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: listTenantServices

Complete the org's billing setup

plaintext

GET /v1/billing/setup/{tenant_id}

Bootstraps the org's billing customer record (free tier) with the signup email; idempotent.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Billing setup complete
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: setupTenantBilling

Delete the spending cap

plaintext

DELETE /v1/billing/spending-cap/{tenant_id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Spending cap removed
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: deleteSpendingCap

Get the spending cap

plaintext

GET /v1/billing/spending-cap/{tenant_id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Current spending cap
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getSpendingCap

Set the spending cap

plaintext

POST /v1/billing/spending-cap/{tenant_id}

Accepts PUT, PATCH and POST on the same path; the body is the cap configuration.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Request body

application/json (required) — schema SpendingCapRequest.

Responses

Status	Description
`200`	Spending cap set
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: setSpendingCap

Get the org's subscription

plaintext

GET /v1/billing/subscription/{tenant_id}

Returns the current subscription with the display amount in the org's pinned currency, is_paid, and any scheduled (pending) plan change.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Current subscription
`401`	Missing or invalid API key
`403`	Not your org
`404`	No subscription
`500`	Internal error

operationId: getSubscription

Cancel the subscription

plaintext

POST /v1/billing/subscription/{tenant_id}/cancel

Cancels at the current period end (the console confirms first).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Subscription cancelled
`401`	Missing or invalid API key
`403`	Not your org
`404`	No subscription
`500`	Internal error

operationId: cancelSubscription

Change the plan (in-place upgrade/downgrade)

plaintext

POST /v1/billing/subscription/{tenant_id}/change

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Request body

application/json (required) — schema ChangePlanRequest.

Responses

Status	Description
`200`	Plan changed (or downgrade scheduled)
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`404`	No subscription
`500`	Internal error

operationId: changePlan

Reactivate a cancelled subscription

plaintext

POST /v1/billing/subscription/{tenant_id}/reactivate

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Subscription reactivated
`401`	Missing or invalid API key
`403`	Not your org
`404`	No subscription
`500`	Internal error

operationId: reactivateSubscription

Get the org's tax info

plaintext

GET /v1/billing/tax-info/{tenant_id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Tax info (GST/VAT registration)
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getTaxInfo

Update the org's tax info

plaintext

POST /v1/billing/tax-info/{tenant_id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Request body

application/json (required) — schema TaxInfoRequest.

Responses

Status	Description
`200`	Tax info updated
`400`	Invalid request
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: updateTaxInfo

Calculate tax for a charge

plaintext

POST /v1/billing/tax/calculate

Applies the org's tax-info settings (GST/VAT, reverse charge, LUT, exemption) to a pre-tax amount. The stored tax profile fills omitted body fields only for a caller authenticated as that tenant; an unauthenticated caller gets the pure computation from the body fields.

Auth: Bearer API key

Request body

application/json (required) — schema object.

Responses

Status	Description
`200`	Tax breakdown for the amount
`400`	Invalid request
`500`	Internal error

operationId: calculateTax

Get usage by model

plaintext

GET /v1/billing/usage/{tenant_id}/by-model

Token usage and cost broken down per AI model.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Usage by model
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getUsageByModel

Get the usage forecast

plaintext

GET /v1/billing/usage/{tenant_id}/forecast

Projected end-of-period spend based on usage so far.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Projected end-of-period spend
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getUsageForecast

Get the usage history

plaintext

GET /v1/billing/usage/{tenant_id}/history

Period-by-period usage history (the BillingPage's usage table).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Usage history
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getUsageHistory

Get the current overage amount

plaintext

GET /v1/billing/usage/{tenant_id}/overage

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Current overage
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getUsageOverage

Get the usage spread

plaintext

GET /v1/billing/usage/{tenant_id}/spread

Returns usage distributed across the billing period (the spend-over- time chart).

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Usage spread across the period
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getUsageSpread

Get the usage summary

plaintext

GET /v1/billing/usage/{tenant_id}/summary

Aggregated usage-and-spend summary for the current period.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`tenant_id`	path	`string`	Yes	Tenant id (UUID)

Responses

Status	Description
`200`	Usage summary
`401`	Missing or invalid API key
`403`	Not your org
`500`	Internal error

operationId: getBillingUsageSummary

GET /v1/public/service-rates

plaintext

GET /v1/public/service-rates

Auth: none

Responses

Status	Description
`200`	The public rate card: one row per billable, enabled, service-mapped non-AI metric. Sell-side only: our_cost_cents never leaves this query.
`404`	Billing not configured on this deployment

operationId: get_public_service_rates