# Bursar — Open-source AI credits and usage billing

> PostgreSQL-native usage metering, prepaid credits, plans, and reserve-settle billing for AI SaaS, available as Python, TypeScript, and Go SDKs.

Version: 2.x

Start with the quickstart. Use tutorials to learn the system, how-to guides to complete production tasks, concepts to understand design decisions, and reference pages for exact API details.

## Table of Contents

- [What Bursar manages](https://zonastery.github.io/bursar/docs/intro.md): Understand the boundary Bursar owns, the guarantees it enforces, and where to begin integrating it.
- [Create your first metered charge](https://zonastery.github.io/bursar/docs/quickstart.md): Install Bursar, publish a pricing configuration, create an account, and record one usage charge.
- [Set up Bursar and create an account](https://zonastery.github.io/bursar/notebooks/why_bursar_and_setup.md): Set up an isolated Bursar environment, publish pricing, create an account, and record the first metered charge.
- [Publish your first pricing configuration](https://zonastery.github.io/bursar/notebooks/first_pricing_config.md): Inspect, validate, publish, and activate the versioned configuration that controls Bursar.
- [Calculate usage costs with the pricing engine](https://zonastery.github.io/bursar/notebooks/pricing_engine.md): Price metered operations without a database and inspect exact-decimal cost breakdowns.
- [Write safe pricing expressions](https://zonastery.github.io/bursar/notebooks/expression_language.md): Evaluate exact-decimal pricing formulas and verify the expression sandbox boundary.
- [Manage the credit lifecycle](https://zonastery.github.io/bursar/notebooks/credit_lifecycle.md): Post purchases and usage charges, handle bucket allocation, issue refunds, and inspect the ledger.
- [Configure plans and allowances](https://zonastery.github.io/bursar/notebooks/plans_and_allowances.md): Assign plans, consume recurring allowances, enforce entitlements, and observe plan changes.
- [Enforce quotas and spend caps](https://zonastery.github.io/bursar/notebooks/quotas_and_spend_caps.md): Read quota state, trigger thresholds, count reservations, and reject usage above a plan limit.
- [Manage credit priority and expiry](https://zonastery.github.io/bursar/notebooks/credit_tiers_and_expiry.md): Prioritize credit buckets, grant expiring value, run the expiry sweep, and audit the result.
- [Protect long-running work with leases](https://zonastery.github.io/bursar/notebooks/leases_and_financial_safety.md): Reserve, renew, settle, release, and expire leases while enforcing account policy atomically.
- [Share credits across a team](https://zonastery.github.io/bursar/notebooks/teams.md): Create a shared team balance, enforce member spend caps, and preserve membership audit history.
- [Query usage analytics](https://zonastery.github.io/bursar/notebooks/analytics.md): Query metered spend by account, model, and day, then inspect aggregate usage statistics.
- [Consume credit lifecycle events](https://zonastery.github.io/bursar/notebooks/events.md): Subscribe to typed credit events and verify post-commit success and business-failure semantics.
- [Integrate subscriptions and auto-recharge](https://zonastery.github.io/bursar/notebooks/subscriptions_and_auto_recharge.md): Configure offers, create checkout intents, process provider events, and enforce auto-recharge policy.
- [Manage pricing configuration with the CLI](https://zonastery.github.io/bursar/notebooks/cli_and_deployment.md): Validate, publish, compare, export, activate, and roll back pricing configuration with the Bursar CLI.
- [Implement a custom credit store](https://zonastery.github.io/bursar/notebooks/custom_stores.md): Inspect the CreditStore contract and the guarantees required from a specialized backend.
- [Validate the complete configuration schema](https://zonastery.github.io/bursar/notebooks/pricing_config_schema.md): Validate and canonicalize the full Bursar configuration, publish it, and inspect its JSON Schema.
- [How-to guides](https://zonastery.github.io/bursar/docs/guides.md): Complete focused tasks for embedding Bursar, configuring credits and billing, and integrating agent tooling.
- [Isolate Bursar tenants](https://zonastery.github.io/bursar/docs/guides/multitenancy.md): Bind each Bursar runtime to a tenant and enforce isolation with row-level security and composite foreign keys.
- [Configure storage backends](https://zonastery.github.io/bursar/docs/guides/storage-backends.md): PostgreSQL is the canonical credit store; optional ClickHouse and S3 adapters route high-cardinality data through a transactional outbox.
- [Build a prepaid credit system for AI SaaS](https://zonastery.github.io/bursar/docs/guides/ai-saas-credits.md): Design an open-source AI credits and usage billing system with atomic admission, reserve-settle charging, and a PostgreSQL ledger.
- [Protect financial invariants](https://zonastery.github.io/bursar/docs/guides/financial-safety.md): Apply exact money, atomic leases, and idempotent mutations at the account boundary.
- [Manage the credit lifecycle](https://zonastery.github.io/bursar/docs/guides/credit-lifecycle.md): Post grants, purchases, usage charges, refunds, expiry, and revocation as canonical ledger entries.
- [Integrate subscriptions and payments](https://zonastery.github.io/bursar/docs/guides/subscription-integration.md): Create provider-backed checkouts and process signature-verified webhooks through Bursar.
- [Instrument Bursar with OpenTelemetry](https://zonastery.github.io/bursar/docs/guides/opentelemetry.md): Add API-only Bursar traces and metrics while keeping SDK and exporter ownership in the host application.
- [Meter Google ADK model calls](https://zonastery.github.io/bursar/docs/guides/google-adk.md): Add replay-safe credit admission and settlement to Google ADK model calls.
- [Install the Bursar agent skill](https://zonastery.github.io/bursar/docs/agent-skills.md): Install the compact Bursar skill so coding agents follow the project workflow and financial safety rules.
- [Concepts](https://zonastery.github.io/bursar/docs/concepts.md): Learn how Bursar turns usage and payment events into policy decisions and append-only accounting records.
- [Architecture](https://zonastery.github.io/bursar/docs/concepts/architecture.md): The Bursar facade and its capabilities — credits, catalog, accounts, billing, and commerce — over the Postgres schema, with migrations and tenant i...
- [Credit accounting model](https://zonastery.github.io/bursar/docs/concepts/data-model.md): Understand accounts, the append-only ledger, credit lots, leases, allowances, and the invariants that connect them.
- [Pricing model](https://zonastery.github.io/bursar/docs/concepts/pricing.md): Understand how operations, measures, rate cards, and price rules produce exact decimal charges.
- [Plans and access control](https://zonastery.github.io/bursar/docs/concepts/plans.md): Understand how plans combine allowed operations, rate cards, allowances, entitlements, quotas, credit policies, and admission controls.
- [Billing and commerce](https://zonastery.github.io/bursar/docs/concepts/billing.md): How billing connects the credit ledger to a payment provider — offer catalog, normalized events, and auto-recharge guardrails.
- [Configuration and catalog revisions](https://zonastery.github.io/bursar/docs/concepts/configuration.md): Understand how one validated BursarConfig document defines pricing, credits, plans, commerce, and immutable catalog revisions.
- [Expression reference](https://zonastery.github.io/bursar/docs/concepts/expressions.md): Look up the safe expression language for pricing formulas, including its allowlisted functions and operators.
- [Database schema](https://zonastery.github.io/bursar/docs/concepts/database-schema.md): Generated ERD for Bursar's PostgreSQL schema.
- [Bursar CLI reference](https://zonastery.github.io/bursar/docs/cli.md): Look up migration, tenant, and configuration commands and their required inputs.
- [Credits service](https://zonastery.github.io/bursar/docs/python-api/credit-manager.md): The bursar credits service — balances and adjustments, metered charging, the lease lifecycle, plans, ledger history, analytics, and team charging.
- [Python API](https://zonastery.github.io/bursar/docs/python-api.md): The bursar Python SDK — Bursar facade, credit manager, pricing engine, and pluggable stores.
- [PricingEngine](https://zonastery.github.io/bursar/docs/python-api/pricing-engine.md): The bursar PricingEngine — database-free pricing from a canonical config document, pricing UsageMetrics, and CostBreakdown results.
- [Stores](https://zonastery.github.io/bursar/docs/python-api/stores.md): bursar stores — PostgresStore, PostgresBillingStore, and the CreditStore contract for custom backends.
- [Credits service](https://zonastery.github.io/bursar/docs/javascript-api/credit-manager.md): The async bursar credits service — balances and adjustments, metered charging, the lease lifecycle, plans, ledger history, analytics, and team char...
- [TypeScript API](https://zonastery.github.io/bursar/docs/javascript-api.md): Use the TypeScript SDK through the Bursar facade, credits service, pricing engine, and pluggable stores.
- [PricingEngine](https://zonastery.github.io/bursar/docs/javascript-api/pricing-engine.md): The bursar PricingEngine — database-free pricing from a canonical config document, pricing UsageMetrics, and CostBreakdown results.
- [Stores](https://zonastery.github.io/bursar/docs/javascript-api/stores.md): bursar stores — PostgresStore, PostgresBillingStore, and the CreditStore contract for custom backends.
- [Go API](https://zonastery.github.io/bursar/docs/go-api.md): Use Bursar from Go with exact decimal amounts, context-aware operations, and the shared PostgreSQL contract.