> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withorb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance alerts

> Detect when a customer’s prepaid‑credit balance is depleted, drops below a threshold, or recovers.

## Alert types

| Alert type            | Fires when the prepaid ledger…                           | Webhook event                       |
| --------------------- | -------------------------------------------------------- | ----------------------------------- |
| **Balance depleted**  | Transitions **> 0 → 0**                                  | `customer.credit_balance_depleted`  |
| **Balance dropped**   | Transitions **≥ configured threshold → below threshold** | `customer.credit_balance_dropped`   |
| **Balance recovered** | Transitions **0 → > 0**                                  | `customer.credit_balance_recovered` |

## Evaluation mechanics

| Trigger category     | Specific events                                                                                                                                           | Notes                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Usage events         | • Real‑time usage that draws down credits from the balance based on the billable metrics on the subscription.                                             | See [Usage‑based triggers](/usage-alerting/overview) for more information about expected latencies. |
| Credit blocks        | • Activation (manual creation, creation due to an automatic allocation on the plan, or as the result of an automated top‑up)<br />• Expiration or voiding | Block mutations may lag usage‑based triggers by a few minutes.                                      |
| Alert config changes | • New balance alert created<br />• Alert threshold added or removed                                                                                       | Forces immediate re‑evaluation so the new configuration is active within seconds.                   |

## Fetching current alert state

Use the [fetch‑alert endpoint](/api-reference/alert/fetch-alert) to retrieve the serialized `balance_alert_status`.\
The object lists each threshold alongside a boolean indicating whether it is *currently* in alert.

## Practical considerations

* If the balance **drops below and then quickly rises above** a threshold, Orb may emit only the final (recovered) state. Rely on `balance_alert_status` serialized on the alert for the ground‑truth snapshot.
* A **depleted** balance on the ledger can lead to *immediate overage charges* depending on plan configuration if usage continues. In order to resolve this, you can:
  * Manually add and backdate a credit block will cover existing overages.
  * Alternatively, enable **top‑ups** to automate this workflow; you can think of a top‑up as a material side effect of a balance alert. Note
    that [top-ups](/product-catalog/prepurchase#automatic-top-ups) also execute with the same tight SLAs as balance alerts, so will typically operate very quickly.