Building a Credit System for AI Services

Pricing AI services is hard. The cost to serve a request varies wildly — a 2-page memo might use 50K tokens, while a 100-page procurement proposal could burn 2M tokens across 20 agents. A flat monthly fee either overcharges light users or subsidizes heavy ones. Pure token-based billing is incomprehensible to non-technical users.

We built a credit system that balances simplicity, fairness, and technical accuracy.

The Pricing Formula

Every review's cost follows a single formula:

cost = ceil((BASE + extra_agents × 0.5) × page_multiplier × deep_multiplier)

Where:
  BASE = 2 credits
  4 core agents included free
  0.5 credits per extra agent beyond 4
  Page multiplier: 1-10p ×1.0, 11-30p ×1.3, 31-60p ×1.6, 61-100p ×2.0, 100+ ×2.5
  Deep review: ×2.0

This formula is designed to be predictable: users can estimate the cost before submitting. A standard 10-page contract with default agents costs 2 credits. A 50-page deep review with 8 specialist agents costs ceil((2 + 2) × 1.6 × 2.0) = 13 credits.

Quote & Confirm Flow

No one likes surprise charges. Before any review starts, the user sees an exact quote:

• •Frontend sends file sizes and configuration to `/api/review/quote`
• •Backend calculates cost and returns a signed JWT "quote token" (valid 15 minutes)
• •User sees the breakdown: base cost, agent cost, page multiplier, deep multiplier, total
• •User confirms → quote token is sent with the upload
• •Backend verifies the token signature and uses the locked-in price

The JWT prevents price manipulation: even if the user modifies the request between quote and upload, the cryptographically signed cost from the original quote is used.

Atomic Credit Deduction

Race conditions are a real concern. If a user rapidly submits two reviews, naive balance checks could allow overdraft. We use a PostgreSQL atomic UPDATE:

UPDATE credits
SET current_credits = current_credits - $amount
WHERE user_id = $uid AND current_credits >= $amount
RETURNING current_credits

If the balance is insufficient, the UPDATE affects zero rows and the review is rejected. No separate SELECT + UPDATE, no TOCTOU vulnerability.

Post-Review Reconciliation

The quote is an estimate — actual token usage may differ. After the review completes, we reconcile: if the actual cost exceeds the quoted price, the difference is charged. We never refund the difference if actual usage is lower, because the user already confirmed the quoted price. This keeps things simple and predictable.

Team Credits

Enterprise users can create teams where members share the owner's credit pool. When a team member submits a review, the system resolves the credit owner (the team admin) and deducts from their balance. The member never sees or manages credits directly — they just use the service.