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

# balance.low

> Sent when an environment's available balance crosses below the low-balance threshold.

<Warning>
  This event is part of the published catalog but is not yet emitted by mintfax. The schema on this page is the target so you can build against it now. Subscribing to `balance.low` today will not return an error, but no deliveries will arrive until the producer ships.
</Warning>

## When it will fire

When the available balance for an environment drops below the configured low-balance threshold. The threshold is set per environment in the dashboard.

The event fires on the transition - it does not refire on every fax billed against a balance that is already below the threshold. If the balance is topped up and then crosses the threshold again, a new `balance.low` is fired.

## What your handler should do

* Trigger your top-up workflow. Whether that is manual, an Approval queue, or an automated charge against your billing source is up to you.
* Persist the event ID. If your top-up workflow is asynchronous, deduplicating on `webhook-id` prevents a webhook redelivery from triggering a duplicate top-up.
* Consider using auto-top-up instead of handling this event manually. Auto-top-up is configured per environment and operates from the same threshold signal without requiring webhook handling.


## OpenAPI

````yaml openapi.json webhook balance.low
openapi: 3.1.0
info:
  title: mintfax API
  version: '1.0'
  description: >-
    Developer-first fax API. Send faxes with a single API call.


    ## Authentication


    Most endpoints require a Bearer token in the `Authorization` header.


    - **Account keys** (`mfx_acct_...`) access account-level endpoints
    (`/account`, `/account/balance`, `/account/transactions`, `/account/keys`).

    - **Environment keys** (`mfx_test_...` for test, `mfx_live_...` for live)
    access operational endpoints (`/environment`, `/faxes`, `/webhooks`,
    `/events`).

    - Registration endpoints (`POST /account/register` and `POST
    /account/register/verify`) do not require authentication.


    ## Base URL


    All API requests use `https://api.mintfax.com/v1` as the base URL.
  contact:
    name: mintfax Support
    email: support@mintfax.com
    url: https://mintfax.com/docs
servers:
  - url: https://api.mintfax.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account-level resources: registration, account info, balances, and API
      keys.
  - name: Environment
    description: >-
      Test and live environment configuration shared across all operational
      requests.
  - name: Fax
    description: Send, list, retrieve, resend, and purge faxes.
  - name: Events
    description: >-
      Read the immutable event log for everything that has happened in the
      environment.
  - name: Webhooks
    description: >-
      Manage webhook endpoints and inspect or replay individual delivery
      attempts.
paths: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      description: |-
        API key as Bearer token. Use an account key (`mfx_acct_...`) for
        `/account/*` endpoints, and an environment key (`mfx_test_...` for
        sandbox, `mfx_live_...` for live) for `/environment/*`, `/faxes`,
        `/webhooks`, and `/events`.
      scheme: bearer

````