Billing

Billing combines subscription plans with a real USD balance held in cents. Token usage is recorded in microcents (1 cent = 10,000 microcents). Deposits raise both balanceCents and cumulativeDepositsCents; the platform fee is waived until cumulative deposits exceed the configured threshold.

Endpoints

Balance and usage summary

GET /api/v1/billing returns the org's billing snapshot:

{
  "success": true,
  "data": {
    "balance": {
      "balanceCents": 0,
      "cumulativeDepositsCents": 0,
      "autoTopupEnabled": false,
      "autoTopupThresholdCents": 500,
      "autoTopupAmountCents": 2500
    },
    "waiver": { "active": true, "remainingCents": 10000 },
    "payment": {
      "stripeConfigured": true,
      "webhookConfigured": true,
      "publishableKeyConfigured": true,
      "directDepositAvailable": false,
      "billingEnforced": true
    },
    "usage": {
      "currentMonth": {
        "inputTokens": 0,
        "outputTokens": 0,
        "cacheReadTokens": 0,
        "cacheWriteTokens": 0,
        "providerCostMicrocents": 0,
        "platformFeeMicrocents": 0,
        "totalChargedMicrocents": 0,
        "totalChargedCents": 0,
        "requestCount": 0,
        "byokRequestCount": 0,
        "totalTokens": 0,
        "monthStart": "2026-05-01T00:00:00.000Z",
        "operationBreakdown": [
          { "operation": "chat", "requestCount": 12, "totalChargedMicrocents": 1234, "totalChargedCents": 1 }
        ]
      }
    },
    "transactions": [
      { "id": "uuid", "type": "deposit", "amountCents": 1000, "stripePaymentIntentId": "pi_...", "notes": null, "createdAt": "..." }
    ],
    "promotions": []
  }
}

Update auto top-up

PATCH /api/v1/billing

Requires the caller to pass assertCanManageBilling. Returns { "updated": true }.

Deposit

POST /api/v1/billing/deposit

When Stripe is configured, the response is a Checkout Session:

{ "success": true, "data": { "checkoutUrl": "https://...", "sessionId": "cs_..." } }

Redirect the user to checkoutUrl. On completion, Stripe sends a webhook to /api/v1/billing/webhooks/stripe, which credits the balance and writes a deposit transaction.

When Stripe is not configured (local/dev), the response is:

{ "success": true, "data": { "deposited": 1000, "method": "direct", "message": "Deposit applied directly (Stripe not configured)" } }

curl -X POST https://alumia.com/api/v1/billing/deposit \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "amountCents": 1000 }'

Subscription checkout

POST /api/v1/billing/subscriptions/checkout

When Stripe is configured, the response is:

{ "success": true, "data": { "checkoutUrl": "https://...", "sessionId": "cs_...", "planId": "team" } }

Redirect the user to checkoutUrl. Custom plans return a validation error and are handled by sales.

Transactions

GET /api/v1/billing/transactions?type=&limit=&page= — Paginated list. Valid type values: deposit, usage, refund, adjustment, platform_fee. Unknown values fall back to no filter.

Pricing

GET /api/v1/billing/pricing — Returns subscription plans, the platform fee rate, per-model rates with the fee already applied, and the list of billable service prices.

Spending analytics

GET /api/v1/billing/spending?period= returns a summary, daily series, and the top agents and models by spend. The period query accepts today, week, month, year, etc. (normalized server-side). Sub-routes (by-model, by-agent, by-project) return single-axis breakdowns over the same period.

Legacy provider keys

GET /api/v1/billing/byok-keys returns the caller's legacy keys (provider, label, fingerprint), never the plaintext.

POST /api/v1/billing/byok-keys is disabled by default and returns BAD_REQUEST while new provider-key setup is unavailable. It can be explicitly re-enabled for controlled maintenance with ALUMIA_BYOK_ENABLED=1.

DELETE /api/v1/billing/byok-keys/:id removes a legacy entry.

Errors