Top up credits
Add purchased credits to a tenant. Purely additive, idempotent on your key, and never replaces existing balances.
https://api.swarmz.net/functions/v1/platform-topupAdds purchased credits to a tenant. The operation is purely additive — it increments the tenant's top-up balance and never replaces or resets existing balances.
Address the tenant by tenant_id or external_ref — supply exactly one.
Parameters
Prop
Type
Request
curl -X POST https://api.swarmz.net/functions/v1/platform-topup \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"external_ref": "whmcs:1234",
"amount": 100,
"idempotency_key": "whmcs:1234:topup-2026-05-23-0001"
}'const res = await fetch('https://api.swarmz.net/functions/v1/platform-topup', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
external_ref: 'whmcs:1234',
amount: 100,
idempotency_key: 'whmcs:1234:topup-2026-05-23-0001',
}),
});
const data = await res.json();import requests
res = requests.post(
"https://api.swarmz.net/functions/v1/platform-topup",
headers={"Authorization": "Bearer sk_live_..."},
json={
"external_ref": "whmcs:1234",
"amount": 100,
"idempotency_key": "whmcs:1234:topup-2026-05-23-0001",
},
)
data = res.json()Response
{
"ok": true,
"balances": {
"included_credits": 0,
"included_credits_used": 0,
"rollover_credits": 0,
"rollover_credits_used": 0,
"topup_credits": 100,
"daily_bonus_limit": 50,
"daily_bonus_used": 0
}
}For platform tenants, only topup_credits, daily_bonus_limit, and daily_bonus_used are meaningful — the other fields are returned for completeness.
Errors
| Status | error | reason | When |
|---|---|---|---|
| 400 | missing_fields | tenant_id or external_ref required | Neither identifier supplied |
| 400 | missing_fields | idempotency_key required | idempotency_key absent |
| 400 | invalid_amount | amount must be a positive finite number | amount non-positive, non-finite, or not a number |
| 401 | unauthorized | — | See Authentication |
| 404 | tenant_not_found | — | No tenant matched the identifier under your account |
| 405 | method_not_allowed | — | Anything other than POST |
| 409 | suspended | — | The tenant is suspended |
| 409 | tenant_not_active | — | The tenant is not in an active state |
| 410 | terminated | — | The tenant has been terminated |
| 429 | rate_limited | per_key / per_ip | Rate limit hit — see Rate limits |
| 500 | topup_failed | RPC message | Top-up failed server-side; safe to retry |
Idempotency
Top-up is idempotent on idempotency_key, scoped per tenant. A retry with the same key is a no-op and returns the current balances rather than adding the amount again. See Idempotency.
Notes
A suspended tenant rejects top-ups
Topping up a suspended tenant returns 409 suspended. Queue the top-up and
replay it after unsuspend. Because the idempotency key is
scoped per tenant, the queued retry remains safe — re-sending it once the
tenant is active applies the credit exactly once.
This endpoint is limited to 60 requests/min per key and 120/min per IP. See Rate limits.
Refresh a tenant's billing cycle
Rollover unused credits and reset the monthly allowance at a billing-cycle boundary. Idempotent per (tenant, cycle anchor).
Suspend a tenant
Reversibly pause a tenant — flip it to suspended, take its public site offline, and tear down running infrastructure. The prior state is captured for unsuspend to replay.