> ## Documentation Index
> Fetch the complete documentation index at: https://tanso.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> Prepaid balances with grants, FIFO draw-down, and a full ledger

Credits in Tanso are a standalone wallet subsystem, linked to subscriptions —
not welded into pricing rules. That keeps two questions separate: *what does
usage cost* (pricing rules) and *what balance pays for it* (credit pools).

## The pieces

| Object           | What it does                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| **Credit model** | Defines a denomination (`api_credits`), rollover policy, and hard-limit behavior                            |
| **Credit pool**  | A customer's balance in one denomination, with running totals for granted / consumed / expired / reversed   |
| **Grant**        | An addition to a pool — plan-included, purchased, or promotional — with optional expiry, drawn down FIFO    |
| **Transaction**  | Append-only ledger entry with `balance_before` / `balance_after`, so every balance is auditable to the unit |

Pools link to subscriptions with a **draw priority** and optional
**draw limit**, so multiple pools can back one subscription and drain in a
defined order.

## How deduction works

When an event arrives for a feature backed by a credit model, credits are
deducted synchronously at ingestion — FIFO across grants, respecting draw
priority. The deduction is stamped into the event's context, and
credit-covered usage is excluded from Stripe meter forwarding so it isn't
billed twice.

If a pool has `hardLimit: true` and the balance can't cover the event, the
event is **rejected at ingestion** — real-time enforcement, not an invoice
surprise.

## Reading balances (Client API)

```bash theme={null}
# All pools for a customer
curl http://localhost:8080/api/v1/client/credits/{customerReferenceId}/pools \
  -H "X-API-Key: $KEY"

# One pool's grants or full transaction history
curl http://localhost:8080/api/v1/client/credits/{customerReferenceId}/pools/{poolId}/grants \
  -H "X-API-Key: $KEY"
curl http://localhost:8080/api/v1/client/credits/{customerReferenceId}/pools/{poolId}/transactions \
  -H "X-API-Key: $KEY"
```

Pool and grant management (creating models, granting credits, reversing
transactions) lives on the admin API and the [MCP server](/mcp)'s admin
tools.

## Design notes worth knowing

* **Deduction assumes 1:1** between usage units and the credit denomination.
* **Expiry is a scheduled job** (`CreditExpirationJob`) — expired grants move
  their remainder to the pool's `total_expired`, visible in the ledger.
* **Plan-included credits** are granted on subscription cycle rollover and
  clawed back on cancellation; upgrades grant the delta.