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

# Notify customers about low credit balance

This guide shows how to warn customers before they run out of credits, and tell them when they have. Stigg sends a webhook when a customer's credit balance crosses a threshold and another when it reaches zero. Your handler turns each one into an email, an in-app banner, or an alert to your team.

## Events

| Event | Fires when |
| - | - |
| [`credit_balance.low`](https://docs.stigg.io/api-reference/credit-balance/credit-balance-low) | The balance falls below one of the configured thresholds |
| [`credit_balance.depleted`](https://docs.stigg.io/api-reference/credit-balance/credit-balance-depleted) | The balance reaches zero |

Thresholds are configured at the environment level, so you can set several alert levels (for example 80%, 50%, and 20% remaining). Each `credit_balance.low` payload includes `thresholdPercentage`, the threshold that was crossed, along with `remainingBalance`, `remainingBalancePercentage`, and the `creditCurrency` the balance is in. Each event's reference page shows its full payload.

To receive these events, add a webhook endpoint in Stigg and subscribe it to both. See [Webhooks](https://docs.stigg.io/documentation/native-integrations/events/webhooks.md) for setup and signature verification.

## Choose a response for each threshold

Escalate the message as the balance drops:

| Remaining balance | Suggested action |
| - | - |
| 80% | Send a reminder email or in-app notification that credits are being consumed |
| 50% | Show an in-app banner suggesting the customer top up soon |
| 20% | Send an urgent notification and suggest [auto-recharge](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/auto-recharge/overview.md) |
| 0% (depleted) | Tell the customer their credits are used up and prompt a top-up |

## Handle the webhooks

```javascript theme={null}
app.post('/webhooks/stigg', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'credit_balance.low': {
      const { customer, creditCurrency, remainingBalancePercentage, thresholdPercentage } = event;

      if (thresholdPercentage <= 20) {
        await sendUrgentLowBalanceEmail(customer, creditCurrency, remainingBalancePercentage);
      } else if (thresholdPercentage <= 50) {
        await showInAppBanner(customer.id, 'Your credits are running low. Consider topping up.');
      } else {
        await sendLowBalanceReminder(customer, creditCurrency);
      }
      break;
    }

    case 'credit_balance.depleted': {
      const { customer, creditCurrency } = event;

      await sendDepletionNotification(customer, creditCurrency);
      await promptTopUp(customer.id);
      break;
    }
  }

  res.status(200).send('OK');
});
```

The same events can drive other responses:

* Alert your customer success team in Slack or Teams when a high-value customer runs low
* Update a usage dashboard with the latest balance
* Restrict access when a balance is depleted, if the currency doesn't use a soft limit

## Recommendations

* Deduplicate on `messageId`, since Stigg can deliver the same webhook more than once.
* Set at least three thresholds so customers have time to act before they run out.
* Include the credit currency name and remaining balance in each message.
* Link directly to the page where customers top up or manage credits.
* Track which notifications lead to top-ups, and adjust thresholds and wording based on the results.


## Related topics

- [Webhooks](https://docs.stigg.io/documentation/native-integrations/events/webhooks.md)
- [Webhook events reference](https://docs.stigg.io/api-and-sdks/api-reference/webhooks/events.md)
- [Credits auto-recharge](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/auto-recharge/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.