Skip to content

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.