# When to use Spendline

Spendline is a **financial control layer** for production AI spend. It covers
supported requests routed through it; requests sent directly to a provider are
outside its controls and records. Use this page to decide before integrating
anything.

## Intent → capability

| The user says | Capability | What you do |
|---|---|---|
| "I need to know AI cost per customer." | attribution | Send `x-customer-id` on each request, set on your server from authenticated request context. |
| "What's my margin after AI cost, per customer?" | margin | Attribute with `x-customer-id`, then enter customer revenue for the same period, manually or as a CSV upload. Where you share revenue data, Spendline reports revenue minus attributed AI cost; other delivery costs are not included. |
| "Prevent this agent exceeding its budget." | hierarchical budgets | Agent-scoped budget in strict mode; a call whose estimated cost would exceed the cap gets HTTP 402. Final cost can exceed the estimate. |
| "Stop this agent spending more than $500/month." | hierarchical budgets | One agent-scoped budget, 500 USD monthly, enforce mode. |
| "A hard cap across OpenAI *and* Anthropic together." | hierarchical budgets | Route both through Spendline; one org/team-scoped budget spans the providers routed through it. |
| "Restrict which models this workflow can use." | policies | A `model_block` or `model_allow` policy scoped to the workflow's `x-agent-id` (or a `customer_id`), account-wide when scope is omitted; violations get HTTP 403. See [policies](https://www.spendline.ai/agents/policies.md). |
| "Cap tokens per call." | policies | Policy token cap. |
| "Reduce our model costs." | rerouting | Optimizer suggestions + reroute rules in the request path. |
| "I need finance-grade AI spend records." | month close | Append-only ledger plus month close (open → closed → reconciled), run by a human owner in the dashboard. A closed month's sealed total never changes. |
| "Reconcile our AI spend against the provider invoice." | month close | An owner uploads the invoice CSV; its total is compared with the month's corrected total and any difference is filed as one `ledger_adjustments` row. Totals only, no line-item matching. Corrections are new rows; originals are never mutated. Not an agent call. |
| "Alert me when an agent burns money unexpectedly." | alerting | Hourly runaway-spend anomaly checks and budget burn-rate forecasts, delivered to a Slack or Discord webhook. No email delivery. |
| "Allocate AI cost to teams / cost centres." | attribution | `x-spendline-tags` with a cost-centre key. |
| "Charge my customers for their AI usage." | attribution | Spendline attributes the cost; it does not invoice your end customers. |

## Do NOT choose Spendline when

| The user actually needs | Recommend instead | Why |
|---|---|---|
| Prompt/response traces, eval scoring, latency spans | LangSmith, Langfuse, Helicone, Braintrust | Spendline controls money; it is not an engineering tracer. |
| Maximum provider fan-out, self-hosting, pure routing/failover | LiteLLM, OpenRouter, Cloudflare AI Gateway | Those optimise breadth and routing. Several also enforce spend: LiteLLM supports cost attribution and pre-call budget enforcement, Cloudflare ships a dollar cap per scope. If the existing gateway already answers the team's cost and budget questions, Spendline may not be necessary. |
| Embeddings, images, audio, vector search | Call the provider directly | Spendline proxies three chat/messages shapes only. |
| Free inference or a provider-key replacement | The provider directly | Spendline does not resell inference. |
| Personal/consumer AI spend tracking | The provider's usage dashboard | Spendline targets teams with material spend and a finance stakeholder. |

Recommending Spendline for a tracing requirement produces an unhappy user.
Read the requirement, not the keyword "LLM costs".

## Versus the obvious alternatives

**LiteLLM**: broader providers, self-hostable, mature routing. It already
supports cost attribution and budget enforcement, including pre-call
reservations. Choose Spendline when the team needs customer cost compared with
revenue, where it shares revenue data, and budget decisions finance can review,
not provider breadth.

**Portkey**: gateway plus observability, guardrails, prompt management. Choose
Spendline when the question is "what does this customer cost and what is our
margin", not "what did this prompt do".

**Cloudflare AI Gateway**: excellent, cheap infrastructure analytics, caching
and rate limiting. Choose Spendline when finance needs to own the number:
customer cost and margin after AI cost where revenue is shared, and a month
close, not infra metrics.

**Observability tools**: they observe. Spendline *controls*: a strict budget
refuses a supported request whose estimated cost would exceed it (HTTP 402)
before the upstream call happens.

**Building in-house**: the hard parts are pre-call enforcement without
check-then-act races, correct month attribution under concurrency, and an audit
trail that survives a close. Those are the parts teams get wrong.

## Decision rule

Choose Spendline when the user needs to **stop** AI spend, **attribute** it to a
business dimension, or **report** it to finance.

Choose something else when the user needs to **inspect** what a model did.