Concepts And Setup
Before diving into any single feature, it helps to see the whole shape of bursar: four pieces that compose into a full credit-billing system for an AI product. This notebook introduces them, runs the smallest possible example against each, and explains the setup code that every later notebook relies on — so those notebooks can skip straight to the feature being taught instead of re-explaining their own scaffolding.
Pricing Basics
Every AI-powered application needs to answer the same fundamental question: how many credits does this request cost? Without a consistent pricing foundation, costs become opaque - different engineers hard-code different rates in different places, audit trails vanish, and changing your pricing requires a code deployment.
Expression Language
Notebook 01 used plain arithmetic inside pricing formulas — enough for simple per-token rates. This notebook covers everything else the formula language supports: floors, caps, conditionals, volume tiers, clamping, rounding, and percentiles — plus the safety model that makes it safe to let formulas be user-editable strings stored in a database.
Credit Lifecycle
Credits flow through a lifecycle: they are added, charged, and sometimes refunded. Understanding this lifecycle is critical to building reliable credit systems.
Plans And Allowances
Most SaaS products offer pricing tiers - Free, Pro, Enterprise - each with a free monthly allowance of credits. bursar tracks per-user plan assignments and monthly usage windows, automatically falling back to the user's credit balance when the free allowance is consumed.
Credit Expiry
Free trial credits should expire after 14 days. Purchased credits might expire in 12 months. Promotional bonuses may expire in 60 days. bursar's credit expiry feature handles all of these scenarios with a single sweepexpiredcredits() function. The pattern is simple: when you add credits to a user's balance, you can set an optional expires_at timestamp. If you set it, a background sweep job finds all expired grants and deducts them from the user's available balance.
Financial Safety
bursar charges after an AI operation completes — but that is exactly when things can go wrong. If you only check the balance before the call and debit after it returns, you have a race: between the check and the debit, other concurrent operations can also pass the check, and a single expensive (or runaway agentic) call can finish costing far more than you estimated. Once the AI work has run, its cost is real regardless of what your ledger says — you cannot un-deliver a response.
Spend Caps
Without spend caps, a single bug or runaway loop can drain a user's entire credit balance in seconds. Spend caps act as safety valves — they limit how many credits a user can consume in a given period, protecting both the user and the platform operator from unexpected costs.
Teams
Individual user balances work well for B2C products where each user pays for themselves. But B2B SaaS needs team accounts — one company with multiple users sharing a single credit pool. bursar's team feature lets you create shared balances, add members, enforce per-user spend caps, and track who spent what. Think of it like a shared bank account with individual debit card limits.
Analytics
Raw credit transactions are a stream of individual events — user X deducted Y credits at time Z. That is hard to read at a glance. bursar's analytics queries aggregate these events into meaningful summaries: total spend per user, breakdown by model, daily trends, and overall statistics. These queries are the foundation for customer-facing dashboards, internal cost analysis, and anomaly detection.
Events
Credit operations are useful on their own, but often you need to react to them — send a Slack alert when a user's balance runs low, update an analytics dashboard on each deduction, or trigger an auto top-up. bursar's event system follows the observer pattern: you emit events when operations happen, and registered handlers react asynchronously.
Custom Store
bursar ships with two store implementations: PostgresStore (production-ready, persistent) and MemoryStore (development, ephemeral). But your application might use a different backend -- Redis for speed, DynamoDB for scalability, SQLite for embedded deployments. The CreditStore abstract base class (ABC) defines the contract that every store must fulfill.
Cli And Deployment
Every previous notebook drove bursar through Python. In production, publishing and rolling back pricing changes is usually a deploy-pipeline or on-call operation, not a Python script — that's what the CLI is for.
Credit Tiers
Not all credits are equal. A signup bonus, a monthly subscription grant, and a credit-card purchase are all "credits" in the user's balance, but a product usually wants them spent in a specific order — burn the free gift before touching money the user paid for — and some of them expire while others don't. Every notebook up to this point used a single scalar balance where none of that distinction was possible.
Subscription Billing
Every SaaS product eventually wires credits to a payment provider your webhook handler receives an event, decides it is legitimate, and calls a plain bursar method. This notebook walks through the three canonical shapes and the bursar primitive each one maps to.