Files · Per-tenant LLM Cost Chargeback for Vertical SaaS

# Per-tenant LLM Cost Chargeback for Vertical SaaS
 
> Track and bill each SMB customer for their AI usage with granular cost attribution.
 
A reference solution demonstrating per-tenant LLM cost tracking, budget enforcement, and Stripe billing chargeback for vertical SaaS platforms.
 
## Features
 
- **Per-tenant cost tracking** — Record and query LLM costs for each tenant using `@reaatech/agent-budget-spend-tracker`
- **Multi-provider support** — Use OpenAI or Anthropic via the Vercel AI SDK
- **Budget enforcement** — Define daily/monthly budgets per tenant and track utilization
- **Anomaly detection** — Detect spend spikes using standard-deviation analysis
- **Stripe billing chargeback** — Generate invoices per tenant based on LLM usage
- **OTel telemetry** — Export cost metrics via OpenTelemetry
 
## Packages
 
### REAA packages
- `@reaatech/agent-budget-spend-tracker` — In-memory circular-buffer spend tracking with O(1) per-scope lookups
- `@reaatech/agent-budget-otel-bridge` — OpenTelemetry span-to-spend bridge via SpanListener
- `@reaatech/agent-budget-types` — Zod-validated types for budgets, scopes, enforcement
- `@reaatech/llm-cost-telemetry` — Core types, utilities, and configuration for cost telemetry
- `@reaatech/llm-cost-telemetry-exporters` — CloudWatch and Loki/Phoenix exporters
- `@reaatech/otel-cost-exporter` — OpenTelemetry-native cost metrics exporter
 
### Third-party packages
- `ai` + `@ai-sdk/openai` + `@ai-sdk/anthropic` — Vercel AI SDK for LLM calls
- `zod` — Runtime schema validation
- `stripe` — Payment processing for chargeback invoices
 
## Quick Start
 
```bash
# Copy env vars and fill in your API keys
cp .env.example .env
 
# Install dependencies
pnpm install
 
# Run tests
pnpm test
 
# Start dev server
pnpm dev
```
 
## Environment Variables
 
| Variable | Description | Required |
|----------|-------------|----------|
| `OPENAI_API_KEY` | OpenAI API key for LLM calls | Yes |
| `ANTHROPIC_API_KEY` | Anthropic API key for LLM calls | Yes |
| `STRIPE_SECRET_KEY` | Stripe secret key for chargeback invoicing | Yes |
| `DEFAULT_DAILY_BUDGET` | Default daily budget per tenant | No (default: 100.0) |
| `OTEL_SERVICE_NAME` | OpenTelemetry service name | No (default: llm-cost-chargeback) |
| `NEXT_PUBLIC_BASE_URL` | Public base URL for server-side fetches | No (default: http://localhost:3000) |
 
## API Endpoints
 
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/tenants` | List all tenants |
| POST | `/api/tenants` | Create a tenant |
| GET | `/api/tenants/:id` | Get tenant details |
| PATCH | `/api/tenants/:id` | Update tenant |
| DELETE | `/api/tenants/:id` | Delete tenant |
| GET | `/api/tenants/:id/costs` | Get cost entries (supports `?rate=true`, `?project=true`, `?startTime=`, `?endTime=`) |
| POST | `/api/tenants/:id/costs` | Record a cost event |
| GET | `/api/tenants/:id/budget` | Get budget utilization |
| POST | `/api/tenants/:id/budget` | Update budget |
| GET | `/api/costs/report` | Generate cost report (use `?tenantId=` for single tenant) |
| POST | `/api/billing/chargeback` | Generate Stripe invoice for a tenant |
| GET | `/api/billing/chargeback` | List invoices for a tenant |
| GET | `/api/costs/anomalies` | Detect spend spikes |
 
## Chargeback Flow
 
1. Each LLM call records a `CostEvent` via the `/api/tenants/:id/costs` endpoint
2. Costs are tracked per tenant using `SpendStore` with O(1) lookups
3. At billing period end, call `POST /api/billing/chargeback` with `{ tenantId, periodStart, periodEnd }`
4. The service creates a Stripe invoice item and generates an invoice for the tenant
5. Invoice status is trackable via `GET /api/billing/chargeback?tenantId=X`
 
## Project Layout
 
```
app/api/           Next.js App Router API routes
src/services/      Business logic (cost tracking, billing, reporting)
src/lib/           Shared types, schemas, constants
src/instrumentation.ts  OTel setup
tests/             Vitest test suite
```
 
## License
 
MIT — see [LICENSE](./LICENSE).