Credits

The credit wallet: prepaid balances with grants, FIFO draw-down, and a full ledger

Credits in Tanso are a standalone credit wallet, 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). Limits are enforced at the moment of use — an empty pool declines the action before you incur the cost of serving it, not at invoice reconciliation.

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, such as plan-included, purchased, or promotional credits, with optional expiry and FIFO draw-down
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 and respecting draw priority. The amount is usageUnits × weight, where the weight comes from the server-side tariff — see Credit weights. With no tariff published, one unit burns one credit. 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 cannot cover the event, the service rejects ingestion with 409 Conflict. The response has success: false and an error message beginning with Credit pool depleted. The transaction rolls back, so the event is not stored and no credits are deducted.

Use an entitlement check before serving the feature for an earlier allow/deny decision. Event rejection remains the final enforcement boundary.

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"

# Current list price of one credit, per denomination (see /credit-prices)
curl http://localhost:8080/api/v1/client/credits/prices -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 is 1:1 by default between usage units and the credit denomination; a published weight tariff changes that server-side.
• Purchased grants carry their sale price. A PURCHASED grant without an explicit unitPrice is stamped with the current price book entry for the pool’s denomination; an explicit unitPrice (a negotiated top-up) always wins.
• 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.

Showing customers their balance

For customer-facing burndown views and depletion forecasts, use the standalone credit forecast packages — they work from Tanso’s pool snapshots or from your own data, with embeddable React components.