Balance
Your prefunded reward balance and top-ups
Money rewards draw from a prefunded balance — Invitebase never custodies your funds, and reward money is kept strictly separate from usage-fee billing. There is one balance per organization per mode; the test-mode balance never moves real money.
The Balance object
| Field | Type | Description |
|---|---|---|
object | string | Always balance. |
available | integer | Funds available for new rewards, in the smallest currency unit. |
held | integer | Funds reserved for pending or in-review rewards. |
currency | string | ISO 4217 code, lowercase, e.g. usd. |
low_balance_threshold | integer | When available drops below this, a balance.low webhook fires. |
auto_reload_enabled | boolean | Whether the balance tops itself up automatically. |
mode | string | test or live. |
Retrieve the balance
GET/v1/balance
Returns the current reward balance for your organization in the key's mode.
curl https://api.invitebase.com/v1/balance \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY"Response — 200 OK:
{
"object": "balance",
"available": 250000,
"held": 12000,
"currency": "usd",
"low_balance_threshold": 50000,
"auto_reload_enabled": true,
"mode": "live"
}Top up the balance
POST/v1/balance/top_ups
Adds funds to the prefunded reward balance, drawn from your payment method via Stripe.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | No | Retries with the same key return the original result. |
amount | body | integer | Yes | Amount in the smallest currency unit (e.g. cents). |
currency | body | string | Yes | ISO 4217 code, lowercase, e.g. usd. |
curl https://api.invitebase.com/v1/balance/top_ups \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
-H "Idempotency-Key: topup-2026-07-09-a" \
-H "Content-Type: application/json" \
-d '{
"amount": 100000,
"currency": "usd"
}'Response — 201 Created: the updated Balance object.
{
"object": "balance",
"available": 350000,
"held": 12000,
"currency": "usd",
"low_balance_threshold": 50000,
"auto_reload_enabled": true,
"mode": "live"
}Returns 400 if the amount or currency is invalid. See Errors.