Your balance is a credit in MXN. You top it up (or receive it as a signup bonus). Each call to the gateway deducts its cost from the balance.
How the balance is computed
Balance = SUM(amount_mxn) across all your credit_transactions
| Type | Sign | When |
|---|
bonus | + | At signup ($50 MXN free) |
recharge | + | When you complete a Stripe recharge |
consumption | - | For each successful gateway call |
refund | + | Manual refund (coming soon) |
adjustment | ± | Manual adjustments by our team (rare) |
Visibility
- Real-time in the dashboard (app.geekhub.mx)
- API endpoint (coming soon):
GET /v1/credits will return your current balance
- Response headers (coming soon): each response will include
x-geekhub-balance-mxn
Threshold and alerts
| Balance | Behavior |
|---|
> $20 MXN | Normal service |
> $0 and < $20 | Normal service + “Low balance” card in dashboard |
≤ $0 | Gateway responds 402 insufficient_balance until you top up |
Set up a cron on your end that checks your balance (when we enable GET /v1/credits) and fires an alert when you’re below 1 day of typical usage.
Per-request detail
In /dashboard/usage you have the full log; each request shows:
- Model used
- Tokens (in / out) or images / seconds
- Exact MXN cost
- P95 latency
- Status (200 / 4xx / 5xx)
- Timestamp
And in /dashboard/billing you have the detail per movement (recharges, bonuses, aggregated consumption).
Race conditions
The balance deduction is atomic at the Postgres transaction level: the consume_credit_on_request() trigger uses pg_advisory_xact_lock per org to serialize concurrent consumption. Even with 100 parallel requests, balance_after always reflects the correct order.
Zero double-charging. Each failed request with cost_mxn > 0 does not generate a consumption (the trigger filters it).
