Two-Tier Billing & Quota Leasing
Understand included monthly quotas, Central IAM commercial top-ups, and hotpath Redis credit leasing.
Two-Tier Billing & Quota Leasing
GNS implements a commercial delivery model engineered to prevent unexpected overage bills while ensuring zero latency on high-throughput dispatch spikes.
1. The Two-Tier Model
┌──────────────────────────────────────────────┐
│ Inbound Request │
└──────────────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Tier 1: Included Plan Quotas (Redis) │
│ - e.g. 1,000 Free OTPs / 10,000 Emails │
│ - Automatically resets on 1st of month │
└──────────┬────────────────────────┬──────────┘
│ │
Quota Available │ Quota Exhausted
│ ▼
│ ┌────────────────────────────────────────┐
│ │ Tier 2: Leased Commercial Balance │
│ │ - Central IAM Commercial Account │
│ │ - Batched Redis credit leases │
│ └──────────────────┬─────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────┐
│ Dispatch Allowed │
└──────────────────────────────────────────────┘Tier 1: Included Monthly Plan Quotas
Every workspace plan (Developer, Startup, Enterprise) comes with a baseline allowance of monthly message dispatches. Included quotas are tracked in Redis and reset on the first day of each billing cycle.
Tier 2: Leased Top-Up Credits
When an application exhausts its included quota, GNS automatically taps into the tenant's commercial credit balance on IITD Central IAM (https://iam.iitdeveloper.com).
2. Distributed Hotpath Credit Leasing
Rather than querying the Central IAM database synchronously on every single message dispatch (which would introduce latency and create a bottleneck), GNS leases blocks of credits (e.g. 100 units) into local Redis:
- Sub-Millisecond Authorization: Balance checks execute in under 1 millisecond via Redis atomic decrements (
DECRBY). - Asynchronous Reconciliation: Background Celery workers settle consumed lease blocks with Central IAM periodically.
- Grace Period: Workspaces configured with overdraft protection can continue delivering critical authentication OTPs even during temporary credit exhaustion.
3. Querying Application Balance (GET /api/v1/billing/usage)
GET /api/v1/billing/usage
Authorization: Bearer <keycloak_token>{
"billing_cycle": "2026-09",
"plan": "developer",
"quotas": {
"email": {
"included": 10000,
"used": 1420,
"remaining": 8580
},
"otp": {
"included": 1000,
"used": 240,
"remaining": 760
}
},
"commercial_balance": {
"currency": "USD",
"available_credits": 45,
"leased_credits": 2.5
}
}