Appearance
Balance System
TiruPay has two separate balance systems that serve different purposes:
- Service Balances - Per-service balances for prepaid credits or usage tracking. Defined via balance types. Can operate in prepaid or pay-as-you-go (PAYG) mode.
- Credit Balance - A prepaid balance used for refunds and credits. Scoped per customer, service, and currency.
How the Models Fit Together
plain
Service
└── Balance Type (e.g. "API Credits", defines rules)
├── Balance (per customer, holds current_balance)
│ └── Balance Usage (one consumption event)
│ └── Usage Item (line item within usage)
│ └── Usage Category (defines price_per_unit)
└── Usage Category (e.g. "GPT-4 Calls", 0.03 per unit)- A Balance Type defines what kind of balance exists and belongs to a service. It defines the balance rules and whether PAYG is allowed.
- A Balance is one customer's instance of that type, holding the
current_balance. - A Usage Category defines a unit price for a specific kind of consumption (e.g. "GPT-4 Calls" at €0.03 per call).
- A Balance Usage is a single consumption event on a balance.
- A Usage Item is a line within a usage, linking to a usage category: "50 GPT-4 Calls × €0.03 = €1.50".
A customer can have multiple service balances - one per balance type. For example, a customer might have an "API Credits" balance and an "LLM Tokens" balance simultaneously.
Prepaid vs. Pay-As-You-Go
Every service balance operates in one of two modes:
Prepaid - The customer buys credits upfront. Usage is deducted immediately and denied if the balance is insufficient. See Service Balances.
Pay-As-You-Go (PAYG) - The balance can go negative. Usage is tracked and billed automatically at the end of each month. PAYG requires a payment mandate and supports plan-based pricing with free allowances, overdraft limits, and country-specific rates. See Pay-As-You-Go.
Relationships
- Customers - Each customer has one Credit Balance and can have multiple service balances.
- Articles - Articles and extensions can grant balance top-ups on purchase, and can be bound to PAYG plans.
- Orders - PAYG usage appears as order positions. Order refunds credit the Credit Balance.
- Services - Balance types are defined per service.
- Price Changes - PAYG plan prices participate in the scheduled price change system.
- Idempotency Keys - Recording usage and reserving balance both deduct money on every call - use idempotency keys so a retried request can't deduct twice.