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)

# 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’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.