Player Balance API
Each title has one currency, and every player holds a balance in it. INVO changes it only through its own money flows (purchases, item purchases, sends, transfers, subscriptions and refunds), and you read it from your server. There is no endpoint to credit or debit a balance directly.
Three numbers per balance
Available
available_balance: what the player can spend or send now. Use it to decide whether a purchase can go ahead.
Reserved
reserved_balance: held for a send or transfer that has started and not yet settled or returned.
Total
total_balance: available plus reserved.
The read endpoints
All take X-Game-Secret-Key and are called from your server, never from a client.
| Endpoint | What it returns |
|---|---|
GET /api/player-balances/player/by-email/{email} | One player's balances in your title. See Get Player Balance. |
POST /api/player-balances/batch | Up to 100,000 players by email and/or player id in one call. |
GET /api/player-balances/stream-all | Every player in your title, streamed, for reconciliation exports. See Player Management. |
GET /api/player-balances/game-summary | Title-wide totals. |
GET /api/sdk/players/activity | One player's money history, newest first. See Player history reads. |
Every write that changes a balance (a purchase, an item purchase, a send or transfer step) returns the result in new_balance; see the write-response contract. To hear about changes as they happen, use webhooks.
Freshness and limits
- • The ledger itself updates the moment a write commits. A by-email read serves from a short cache (up to 5 minutes; batch reads are not cached) that INVO clears whenever its purchase, item purchase, send and transfer paths change that player. For the balance a write just produced, use its
new_balance. - • Per-endpoint limits are on Rate Limits.