---
title: "Balance empty event"
method: POST
path: "balance.empty"
tags: ["Webhook Events"]
---

# Balance empty event

`POST balance.empty` (webhook)

Balance billing only. The balance reached $0 and no auto top-up covered it (auto top-up off, the card declined, or the monthly limit reached), so new pay-per-use (SMS, calls, numbers, X and the rest) answers 402 with `code` until the balance is funded.

### When it fires

Once per time the balance runs out, within about a minute of the usage that emptied it. Funding the balance and running out again fires it again.

### Who receives it

The billing owner's endpoints, like `balance.low`. Restricted keys need the `money` resource group.

### How to act

Send the user to `fundingUrl`, or, for `usage_limit_reached`, raise `monthlyLimitCents` with `PATCH /v1/balance/auto-recharge`.

## Payload

- WebhookPayloadBalanceEmpty
  - `id` string, required: Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource.
  - `test` boolean: Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do.
  - `event` 'balance.empty', required
  - `balance` object, required
    - `spendableCents` integer, required: What pay-per-use can spend, in USD cents: 0 or below (usage already in flight can take it under 0).
  - `code` 'insufficient_balance' | 'usage_limit_reached', required: The 402 code pay-per-use calls get until the balance is funded. `usage_limit_reached` when the auto top-up monthly limit is what keeps it at $0.
  - `fundingUrl` string, uri, required: Dashboard link that opens the Add funds drawer in Billing.
  - `timestamp` string, date-time, required: UTC time at which Zernio generated this event. Retries and redeliveries keep the original value.

## Acknowledgement `200`

Webhook received successfully

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/a79c233ebf22?raw)