Aanchal Parmar
Product Marketing Manager, Flexprice
The Problems You Don't Think About Until They Hit You
The concurrency problem. Two requests arrive 50 milliseconds apart. Both read the same balance: $1.20. Both pass the balance check. Both get served. The customer now owes $2.40 against a $1.20 balance.
Flexprice handles this at the wallet operation level with an advisory lock on the wallet before any credit or debit. The lock is acquired before reading the wallet state within a transaction, so concurrent modifications serialize. The wallet's debit flow goes: acquire lock, read state, validate amounts, consume eligible credits in expiry order, create the transaction record, update balance atomically, release lock, publish webhook event. An IdempotencyKey on wallet operations means retries don't double-debit.
The expiry ordering problem. A customer has three credit tranches: 500 credits expiring in 5 days, 1,000 credits expiring in 30 days, and 2,000 credits expiring in 90 days. Your system consumes them FIFO: oldest first. The 2,000 credits, issued first, get consumed. The 500 credits expire five days later, unused. The customer lost credits they legitimately purchased.
Flexprice's debit algorithm uses expiry-first consumption: soonest-to-expire credits are always consumed before longer-lived ones. Within credits sharing the same expiry, priority ordering applies. This is the correct default for nearly every use case, and it's one of those things that's easy to specify and surprisingly hard to implement correctly under load.
The stale cache problem. This is the one from the opening. Real-time balance checks are more expensive than cached reads. But for credit gating, the decision to use a cached balance needs to be explicit. It shouldn't be something that happens because someone added caching at the middleware layer without realizing it was being used for access control.
The Flexprice balance endpoint's get_from_cache parameter makes the caching decision explicit per call. For a credit gate check, you want get_from_cache=false unless you've done the math on what stale reads cost you at your traffic volume.
The threshold alert problem. A customer's balance is depleting but hasn't hit zero yet. Their batch job will run in 6 hours. Their current burn rate will exhaust the account in 4 hours. Without proactive notification, the job fails mid-run.
Wallet balance alerts fire via Kafka when the balance crosses configured critical, warning, and info thresholds. The CheckWalletBalanceAlert method evaluates the balance and triggers state transitions from OK through info, warning, and into in_alarm. The system throttles alerts at the customer level via in-memory cache to prevent spam during rapid consumption, but ForceCalculateBalance: true bypasses the throttle for critical path checks.
The auto top-up problem. Some customers want credits to replenish automatically when the balance falls below a threshold. The AutoTopup field on a wallet, combined with a configured threshold, handles this. When the balance alert check detects a balance below the auto top-up threshold, triggerAutoTopup() fires. It either creates a new invoice-backed credit or directly credits the wallet depending on the AutoCompletePurchasedCreditTransaction setting.
Where This Breaks If You Build It Yourself
The actual gating check (two API calls before serving, one event after) is not complex code. You could write it in an afternoon.
What takes months to get right is everything underneath the check itself.
Selecting credits by expiry date under concurrent load requires advisory locking at the wallet level, not application-level checks. Making balance reads sub-100ms requires an aggregate table architecture, not raw event scans. Threshold alerts that fire before customers hit zero require a Kafka pipeline with per-customer throttling. Idempotency on retries requires explicit keys on every wallet operation. Soft limits that don't cut off customers mid-request require those limits to be configured per-entitlement, not as a global billing setting.
Each piece is independently solvable. The problem is they need to work together, and they interact. A change to expiry ordering logic can break concurrent debit behavior. Adding a cache to the balance check invalidates the alert threshold logic. None of this shows up in testing.
Teams that build credit gating in-house typically get the happy path right in sprint one. They find the edge cases in production, over the next 18 months, one customer incident at a time.
If you're pressure-testing a credit-gating implementation before it ships, we can walk through the specific scenarios your architecture needs to handle. No pitch, just a look at where the gaps usually appear.
What's the difference between credit gating and rate limiting?
What should happen when a customer's balance hits zero mid-request?
How do you handle credit expiry without surprising customers?
How do you check a customer's current usage against their entitlement limit?
What's the right architecture for credit gating at very high request volumes?
