Billing

Read credit packages, buckets, usage, budgets, top-ups, subscriptions, and invoices.

Billing combines subscription packages with org-scoped credits. One Alumia credit equals $0.01 of managed usage value and is stored as integer credit microunits. Managed model and platform-operation usage consumes fractional credits from monthly, promo, top-up, refund, or adjustment buckets. BYOK model tokens cost 0 Alumia credits, while Alumia-paid infrastructure remains capped or metered separately.

Endpoints

Method	Path	Description
`GET`	`/api/v1/billing`	Credit account summary, active package, subscription status, balances, and spend-pause state.
`GET`	`/api/v1/billing/catalog`	Package catalog, top-up packages, Stripe lookup keys, and fractional rate-card policy.
`GET`	`/api/v1/billing/buckets`	Paginated credit buckets with available, granted, consumed, and expiration fields.
`GET`	`/api/v1/billing/ledger`	Paginated immutable credit ledger entries.
`GET`	`/api/v1/billing/usage`	Usage events and user-facing credit breakdowns by model, operation, project, agent, and session. Provider internal cost and margin fields are not returned.
`GET`, `PUT`	`/api/v1/billing/budgets`	List or upsert org, user, project, agent, and session credit budgets. Writes require billing admin permission and fresh step-up auth.
`POST`	`/api/v1/billing/top-ups/payment-intent`	Create a Stripe PaymentIntent for an allowed credit top-up package.
`POST`	`/api/v1/billing/subscriptions/checkout`	Start Stripe-hosted Checkout for a paid package.
`POST`	`/api/v1/billing/subscriptions/portal`	Start Stripe Billing Portal for subscription, invoice, and tax management.
`GET`	`/api/v1/billing/invoices`	List sanitized Stripe subscription invoices and top-up receipts without exposing Stripe customer IDs, subscription IDs, payment intent IDs, API keys, or webhook secrets.
`POST`	`/api/v1/billing/promotions/claim`	Claim eligible phone-verified signup promotions into credit buckets.
`POST`	`/api/v1/billing/admin/adjustments`	Platform-admin credit grant, revoke, refund, expiration, pause, resume, or explanatory ledger action.
`GET`	`/api/v1/billing/rate-card`	Active user-facing model/tool credit prices. Provider internal cost and margin fields are omitted.
`GET`, `POST`	`/api/v1/billing/admin/rate-cards`	Platform-admin versioned model/tool rate-card management, provider internal cost, user-facing credit charge, margin analytics, negative-margin alerts, and audit-backed changes.

Account Summary

GET /api/v1/billing returns the org's current credit account:

{
  "success": true,
  "data": {
    "account": {
      "orgId": "uuid",
      "planId": "pro",
      "subscriptionStatus": "active",
      "availableCredits": 1842.25,
      "availableCreditMicrounits": 1842250000,
      "spendPausedAt": null,
      "spendPausedReason": null
    },
    "balances": {
      "monthly": { "credits": 1500, "creditMicrounits": 1500000000 },
      "promo": { "credits": 342.25, "creditMicrounits": 342250000 },
      "topUp": { "credits": 0, "creditMicrounits": 0 }
    },
    "package": {
      "id": "pro",
      "name": "Pro",
      "monthlyCredits": 2000
    }
  }
}

Budgets

PUT /api/v1/billing/budgets

Field	Type	Description
`scope`	string	`org`, `user`, `project`, `agent`, or `session`.
`limitCredits`	number	Maximum credits for the period. Fractional values are allowed.
`period`	string	`day`, `month`, or `total`.
`userId` / `projectId` / `agentId` / `sessionId`	string	Required when the scope targets a specific entity. The entity must belong to the org.
`alertThresholds`	number[]	Optional threshold percentages that trigger usage warnings.

The ledger blocks managed spend when an applicable budget is exhausted. Crossing configured thresholds records the new threshold and sends a non-blocking usage warning.

Top-Ups

POST /api/v1/billing/top-ups/payment-intent

Pass a top-up package id from /api/v1/billing/catalog. Billing verifies the active package allows top-ups, creates a Stripe PaymentIntent, and grants a paid top-up credit bucket when Stripe confirms payment through the webhook.

Invoices, receipts, and accounting

GET /api/v1/billing/invoices returns customer-visible Stripe documents: subscription invoices and paid top-up receipts. The route returns invoice URLs, receipt URLs, status, dates, and amounts, but not Stripe customer IDs, subscription IDs, payment intent IDs, client secrets, API keys, or webhook secrets. For payment methods, tax IDs, and full subscription invoice management, open the Stripe Billing Portal through POST /api/v1/billing/subscriptions/portal.

Credits are managed usage units, not stored cash balances. Agent Wallet card reserves and Stripe Issuing authorizations remain separate from Billing credits and are documented under Agent Wallet.

Promotions

POST /api/v1/billing/promotions/claim applies eligible org promotions after phone verification. The seeded EARLY_BIRD promotion grants 1,000 promo credits to the first 1,000 eligible users (amountCents: 1000, requiresPhoneVerification: true).

Errors

Code	When
`UNAUTHORIZED`	No valid key.
`PAYMENT_REQUIRED`	Managed credits, package limits, or applicable budgets do not allow the requested paid operation.
`FORBIDDEN`	Caller lacks billing-manage role, platform-admin permission, or fresh step-up auth where required.
`BAD_REQUEST`	Unknown package/top-up id, invalid budget scope, disabled BYOK setup, or invalid pagination/filter values.

Search docs