Appearance
Example: PAYG Usage-Based Billing (ChatChatter)
ChatChatter is a small example project that lets users chat with LLMs (OpenAI and Anthropic models, via LangChain) and pays for the tokens it consumes. It bills every message in one of two ways: prepaid credits (buy a pack, then chat until it runs out) or pay-as-you-go (no upfront purchase, billed automatically at the end of the month).
This guide walks through the example's source code and explains, step by step, how it maps onto TiruPay's Balance System - in particular Pay-As-You-Go (PAYG), whose core concepts (PAYG Plan, PAYG Plan Price, PAYG Plan Price Item) are the main focus of this guide. Where FitnessQuasar demonstrates Features and a single consumable prepaid balance, ChatChatter demonstrates multi-category usage metering, the reserve/complete/cancel flow used by both balance types, and PAYG billing end-to-end.
Example project, not production code
ChatChatter is provided for illustration only. It is intentionally small and skips things a real integration would need (see Next steps for production at the end of this guide).
Architecture at a glance
As with FitnessQuasar, ChatChatter's own frontend never talks to TiruPay directly - every interaction with TiruPay is brokered by ChatChatter's backend (connectors/tiru.py), which holds the TiruPay service credentials. The browser is only ever handed off to TiruPay's hosted frontend for checkout, PAYG activation, and mandate management:
plain
┌─────────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐
│ ChatChatter │ API │ ChatChatter │ API │ TiruPay │
│ Frontend (React) │◄──────►│ Backend (FastAPI) │◄──────►│ API │
│ :9101 │ │ :9102 │ │ :8100 │
└──────────┬──────────┘ └───────────┬──────────┘ └──────────┬──────────┘
│ │ │
│ chat message (stream) │ reserve → complete │
│─────────────────────────────────►───────────────────────────►|
│ │ │
│ full-page redirect │ identity token exchange │
└──────────────────────────────►│─────────────────────────────►│
│ │
│ redirect w/ auth code │
│◄─────────────────────────────┘
│
▼
┌──────────────────┐
│ TiruPay Frontend │
│ :5173 │
└──────────────────┘Two flows share this architecture: the chat/billing flow (top arrow - every message sent) and the checkout/PAYG-management flow (bottom arrows - buying credits, activating PAYG, managing the SEPA mandate), which reuses the exact JWT Token Exchange bridge documented in the FitnessQuasar example's Step 2.
Prerequisites & environment variables
Copy example.env to .env and fill in the values below. Most come from your TiruPay Service configuration; the balance/category/plan IDs are printed by the provisioning script in Step 1.
| Variable | Where it comes from |
|---|---|
TIRUPAY_API_URL | The base URL of the TiruPay API you're integrating with. |
TIRUPAY_SERVICE_ID | Your Service ID. |
TIRUPAY_JWT_TOKEN | A Service account API key - issued by an Admin, same as in FitnessQuasar. Sent as Authorization: Bearer ... on every request to TiruPay. |
TIRUPAY_JWT_SECRET / TIRUPAY_JWT_ALGORITHM | The shared secret used for JWT Token Exchange, for the TiruPay-login bridge (checkout, PAYG activation, mandate management). |
TIRUPAY_FRONTEND_URL | The base URL of the TiruPay frontend the user gets redirected to. |
TIRUPAY_PREPAID_BALANCE_TYPE_ID, TIRUPAY_PREPAID_INPUT_CATEGORY_ID, TIRUPAY_PREPAID_OUTPUT_CATEGORY_ID | The prepaid balance type and its two usage categories. |
TIRUPAY_PAYG_BALANCE_TYPE_ID, TIRUPAY_PAYG_INPUT_CATEGORY_ID, TIRUPAY_PAYG_OUTPUT_CATEGORY_ID, TIRUPAY_PAYG_PLAN_ID | The PAYG balance type, its two usage categories, and the PAYG Plan activated on it. |
TIRUPAY_SEPA_PAYMENT_METHOD_ID, TIRUPAY_CREDIT_CARD_PAYMENT_METHOD_ID | Payment methods: SEPA for recurring PAYG billing, credit card for one-time credit-pack purchases. |
TIRUPAY_CREDIT_PACK_CATEGORY_ID | The article category the prepaid credit-pack articles live in. |
Never expose the service API key to the frontend
TIRUPAY_JWT_TOKEN authenticates as your Service account and can manage all data in your TiruPay service. It is only ever used in backend code (connectors/tiru.py) and must never be sent to, or read by, the browser.
Step 1 — Two balance types, two billing models
Per TiruPay's model, prepaid and PAYG are two entirely separate balance types with their own usage categories - a customer can hold both at once and pick which one pays for a given message. ChatChatter provisions both up front with a one-off script, scripts/setup_tiru.py:
python
step("Creating balance types")
prepaid_type = post(
"/service/balances/types",
{"name": "Prepaid Credits", "service_id": SERVICE_ID, "payment_mode": "prepaid"},
)
payg_type = post(
"/service/balances/types",
{"name": "Pay-As-You-Go", "service_id": SERVICE_ID, "payment_mode": "payg"},
)
step("Creating usage categories")
prepaid_input = post(
"/service/balances/usage-categories",
{"name": "prepaid_input_tokens", "balance_type_id": prepaid_type["id"], "price_per_unit": "0.001"},
)
prepaid_output = post(
"/service/balances/usage-categories",
{"name": "prepaid_output_tokens", "balance_type_id": prepaid_type["id"], "price_per_unit": "0.003"},
)
payg_input = post(
"/service/balances/usage-categories",
{"name": "payg_input_tokens", "balance_type_id": payg_type["id"]},
)
payg_output = post(
"/service/balances/usage-categories",
{"name": "payg_output_tokens", "balance_type_id": payg_type["id"]},
)Input and output tokens are modeled as separate usage categories because they're priced differently - output tokens cost 3x input tokens here, mirroring how LLM providers price completions. Note that the PAYG categories are created without a price_per_unit - for PAYG, the rate doesn't live on the category itself, but on the PAYG plan's price items, covered next.
Step 2 — The PAYG Plan, PAYG Plan Price, and Price Items
This is the part of TiruPay's model that takes the most unpacking, so it's worth going through slowly with ChatChatter's real values. The setup script provisions all three levels in one go:
python
step("Creating PAYG plan, price, and price items")
payg_plan = post(
"/service/balances/payg-plans",
{
"balance_type_id": payg_type["id"],
"name": "Standard Usage",
"unit_scale": 1000,
"monthly_free_units": "50",
"limit_payg": "20.00",
},
)
payg_price = post(
f"/service/balances/payg-plans/{payg_plan['id']}/prices",
{"country_code": "DE"},
)
post(
f"/service/balances/payg-plan-prices/{payg_price['id']}/items",
{"usage_category_id": payg_input["id"], "price_per_unit": "0.001", "tax_category_id": tax_category["id"]},
)
post(
f"/service/balances/payg-plan-prices/{payg_price['id']}/items",
{"usage_category_id": payg_output["id"], "price_per_unit": "0.003", "tax_category_id": tax_category["id"]},
)PAYG Plan: the rate-card template
The PAYG Plan ("Standard Usage") is the reusable pricing policy for the Pay-As-You-Go balance type - it doesn't itself carry a currency or a €/unit rate. Three fields matter here:
unit_scale = 1000- ChatChatter records raw token counts asunits_used(e.g.2000for 2,000 input tokens). TiruPay divides recorded units byunit_scalebefore pricing them, so withunit_scale = 1000, every 1,000 tokens is one billable unit. This is why the price items below read as "€0.001 per unit" rather than "€0.000001 per token" -unit_scaleis what lets you price in convenient round numbers while still metering in the smallest unit your code naturally produces (tokens).monthly_free_units = "50"- 50 billable units free per month, i.e. 50,000 raw tokens (50 × unit_scale). Since nothing overrides it below, this allowance is a shared pool across bothpayg_input_tokensandpayg_output_tokens- the first 50 units of input+output combined each month cost nothing.limit_payg = "20.00"- the default overdraft cap. Note this number has no currency attached at the plan level - it's a template value that price containers below should generally re-state explicitly in their own currency.
A plan on its own can't be activated by a customer yet, though - it has no price for any country.
PAYG Plan Price: the plan, made concrete for one country
A PAYG Plan Price is a container that instantiates the plan for exactly one country. ChatChatter creates one, for Germany:
python
payg_price = post(
f"/service/balances/payg-plans/{payg_plan['id']}/prices",
{"country_code": "DE"},
)Why does the plan need a separate object per country at all, instead of just having a price directly? Two reasons: tax categories are country-specific (Germany's VAT category isn't the US's sales-tax category), and currencies differ - a plan sold in Germany and the US needs two containers with two sets of rates, even if the underlying allowance policy is the same. ChatChatter only sells in Germany, so there's exactly one price container - but the model is built to support the same plan being priced differently per market. This price container leaves monthly_free_amount, monthly_free_units, and limit_payg all unset, meaning it inherits every default from the plan above (50 free units/month, €20 overdraft cap).
PAYG Plan Price Item: the actual rate, per usage category
Each price container holds one PAYG Plan Price Item per usage category - this is where the real €/unit rate and tax category finally live:
python
post(
f"/service/balances/payg-plan-prices/{payg_price['id']}/items",
{"usage_category_id": payg_input["id"], "price_per_unit": "0.001", "tax_category_id": tax_category["id"]},
)
post(
f"/service/balances/payg-plan-prices/{payg_price['id']}/items",
{"usage_category_id": payg_output["id"], "price_per_unit": "0.003", "tax_category_id": tax_category["id"]},
)So the full chain for a German ChatChatter customer is:
plain
PaygPlan "Standard Usage" (unit_scale=1000, 50 free units/mo, €20 overdraft cap)
└─ PaygPlanPrice (country_code=DE) (inherits all three defaults above)
├─ PaygPlanPriceItem (payg_input_tokens) price_per_unit = €0.001
└─ PaygPlanPriceItem (payg_output_tokens) price_per_unit = €0.003A worked example
Say a single chat message uses 2,000 input tokens and 500 output tokens. Following the PAYG cost formula - scaled_units = units_used / unit_scale, then item_cost = scaled_units × price_per_unit:
plain
input: 2000 / 1000 = 2 billable units × €0.001 = €0.002
output: 500 / 1000 = 0.5 billable units × €0.003 = €0.0015
total_cost = €0.0035Across a whole month, once the customer's combined input+output usage exceeds the 50 free billable units (50,000 raw tokens), every additional billable unit is charged at these same per-category rates - up to the €20 overdraft cap, beyond which further usage is rejected until the next billing cycle resets it.
Why an activation snapshot matters
When a customer activates this plan, TiruPay creates a PAYG Activation - an immutable snapshot of the plan price's fields (unit_scale, free allowance, limit_payg, currency, and each price item's price_per_unit) at that moment. This is what makes plans and prices two separate concepts instead of one: the plan and price can keep evolving (a scheduled price change can raise payg_input_tokens to €0.0015 next quarter), but every already-activated customer keeps paying the rate they signed up at, until they explicitly accept a price-change consent request. This snapshot is also exactly what TiruPay itself uses to price every reservation ChatChatter creates against this balance - which is why ChatChatter itself never needs to read category_prices or unit_scale at all. See the next step.
Step 3 — Checking that PAYG is activated (nothing more)
The only thing ChatChatter itself checks about PAYG before billing a message is whether it's activated - not what it costs. connectors/tiru.py:
python
def get_active_payg_activation(balance_id: str) -> dict | None:
"""Get the currently active PAYG activation for a balance, or None if PAYG isn't active."""
response = requests.get(
f"{TIRUPAY_API_URL}/service/balances/items/{balance_id}/active-payg-activation",
headers=HEADERS,
)
if response.status_code == 404:
return None
if response.status_code != 200:
raise Exception(f"Failed to get PAYG activation on TiruPay: {response.text}")
return response.json()routes/conversations.py calls it purely for its truthiness, to show a friendly error instead of a failed reservation if the customer never activated PAYG:
python
if not get_active_payg_activation(balance["id"]):
return StreamingResponse(
_error_stream("Pay-as-you-go is not activated for your account."),
media_type="text/event-stream",
)Notice what's not here: no local read of activation["category_prices"] or activation["unit_scale"], and no local cost formula. ChatChatter deliberately never reimplements the pricing math from Step 2 - it hands TiruPay raw units_used and lets TiruPay price them from the very same activation snapshot, server-side, in the next step's reservation call. This is the one rule this example follows for all balance types: estimate quantities (tokens), never estimate cost.
Step 4 — Estimating cost before calling the LLM
Both billing paths need a cost estimate before the LLM responds, since the real token counts aren't known yet. connectors/llm.py:
python
def estimate_tokens(messages: list[dict], max_output_tokens: int = DEFAULT_MAX_OUTPUT_TOKENS) -> tuple[int, int]:
"""
Estimate (input_tokens, output_tokens) for a chat request before calling the LLM.
Input is estimated with a generic tokenizer (close enough across providers for a
pre-flight cost estimate). Output is estimated as the configured max_tokens ceiling,
i.e. the worst case - this is what gets reserved on the balance up front.
"""
text = SYSTEM_PROMPT + "\n" + "\n".join(m["content"] for m in messages)
input_estimate = len(_encoding.encode(text))
return input_estimate, max_output_tokensInput tokens are estimated with tiktoken; output is estimated as the model's configured max_tokens ceiling - the worst case, since the actual response could be shorter.
Step 5 — One reservation flow for both balance types
routes/conversations.py's POST /conversations/{id}/messages/stream used to branch into two different flows here - reserve for prepaid, a separate sufficiency-check for PAYG. It doesn't anymore: both balance types now go through the exact same reserve → complete/cancel mechanism. Only the usage categories differ:
python
input_estimate, output_estimate = estimate_tokens(lc_messages)
if data.balance_mode == BalanceMode.prepaid:
balance = get_or_create_balance(customer_id, TIRUPAY_PREPAID_BALANCE_TYPE_ID)
items = [
{"usage_category_id": TIRUPAY_PREPAID_INPUT_CATEGORY_ID, "units_used": input_estimate},
{"usage_category_id": TIRUPAY_PREPAID_OUTPUT_CATEGORY_ID, "units_used": output_estimate},
]
insufficient_detail = "Insufficient prepaid credits - please top up."
else:
balance = get_or_create_balance(customer_id, TIRUPAY_PAYG_BALANCE_TYPE_ID)
if not get_active_payg_activation(balance["id"]):
return StreamingResponse(
_error_stream("Pay-as-you-go is not activated for your account."),
media_type="text/event-stream",
)
items = [
{"usage_category_id": TIRUPAY_PAYG_INPUT_CATEGORY_ID, "units_used": input_estimate},
{"usage_category_id": TIRUPAY_PAYG_OUTPUT_CATEGORY_ID, "units_used": output_estimate},
]
insufficient_detail = "Pay-as-you-go overdraft limit reached for this month."
try:
reservation = reserve_balance_usage(
balance["id"], items, title="Chat message", description="Estimated cost, settled after the response"
)
except InsufficientBalanceError:
return StreamingResponse(_error_stream(insufficient_detail), media_type="text/event-stream")reserve_balance_usage computes the cost of items from the balance's pricing (the prepaid categories' flat price_per_unit, or the PAYG activation snapshot from Step 2) and checks it against the balance itself - a 402 becomes InsufficientBalanceError either way. For prepaid that means "not enough credits left"; for PAYG it means "this would exceed the overdraft limit" (limit_payg). ChatChatter branches only on the message shown to the user, not on the mechanism used to get there.
After the LLM streams its response and the real token counts are known (connectors/llm.py's stream_chat), both paths settle the same way:
python
if balance_mode == BalanceMode.prepaid:
actual_items = [
{"usage_category_id": TIRUPAY_PREPAID_INPUT_CATEGORY_ID, "units_used": input_tokens},
{"usage_category_id": TIRUPAY_PREPAID_OUTPUT_CATEGORY_ID, "units_used": output_tokens},
]
else:
actual_items = [
{"usage_category_id": TIRUPAY_PAYG_INPUT_CATEGORY_ID, "units_used": input_tokens},
{"usage_category_id": TIRUPAY_PAYG_OUTPUT_CATEGORY_ID, "units_used": output_tokens},
]
usage = complete_balance_usage(reservation["id"], actual_items)If the LLM call fails after the reservation was made, cancel_balance_usage refunds it - regardless of balance type. usage["total_cost"] and usage["id"] (the TiruPay BalanceUsage id) are persisted onto the chat message row for the app's own history/analytics.
Why bother reserving for PAYG at all, if it can go negative anyway?
A pure sufficiency check (as an earlier version of this example did) still requires computing an estimated cost somewhere to check against limit_payg - and the only way to do that without reimplementing TiruPay's own pricing logic locally is to let TiruPay compute it, which is exactly what a reservation does. Reserving doesn't change that PAYG can go negative up to limit_payg on completion - it just means the pre-flight check against that limit is delegated to TiruPay instead of duplicated in application code that would drift out of sync with the plan's real prices.
Step 6 — Balance overview & PAYG activation/mandate endpoints (brief)
routes/billing.py exposes the supporting endpoints the frontend needs around the core chat flow:
GET /billing/overview- combines the prepaid balance, PAYG balance/activation status, and mandate status into one response for the UI.GET /billing/credit-packs/POST /billing/credit-packs/{article_id}/checkout- lists and buys prepaid top-up Articles.POST /billing/payg/activate//payg/change-mandate//payg/deactivate- redirect the browser to TiruPay's hosted PAYG activation and SEPA mandate-management pages, or deactivate PAYG directly viadeactivate_payg.
All three redirect endpoints reuse the same JWT Token Exchange bridge as checkout (see Architecture at a glance) - they're not repeated in full here since they follow exactly the pattern already documented in the FitnessQuasar example's Step 2 and Step 3.
Running the example end-to-end
bash
cp example.env .env
# fill in the TiruPay values described aboveProvision the TiruPay-side objects (balance types, usage categories, PAYG plan/price, credit-pack articles) and paste the printed IDs into .env:
bash
uv sync
uv run python scripts/setup_tiru.pyBackend:
bash
uv run fastapi run --port 9102Frontend:
bash
cd frontend
bun install
bun run devNext steps for production
This example intentionally keeps things minimal. Before basing a real integration on it, consider:
- Webhooks. ChatChatter never learns about a PAYG price change consent request, a failed mandate charge, or a subscription lifecycle event asynchronously. Implement a webhook receiver instead of relying only on the customer coming back through the app.
- API key rotation. The Service API key (
TIRUPAY_JWT_TOKEN) expires after 180 days by default - see Service Account API Keys. - Token estimation is a worst case. Reserving the configured
max_tokensceiling as the output estimate over-reserves on the balance for every response shorter than the ceiling; a production integration may want a tighter estimate or a lower ceiling. - Read more: Pay-As-You-Go (PAYG), Service Balances, Balance System.