---
title: "Update usage-alert settings"
method: PATCH
path: "/billing/usage-alerts"
tags: ["Billing"]
---

# Update usage-alert settings

`PATCH /billing/usage-alerts`

## Request

- Base URL: `https://api.axilio.ai/api/v1`
- URL: `https://api.axilio.ai/api/v1/billing/usage-alerts`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api-2/docs/billing/usage-alerts/patch.ts> (a function with typed inputs; its response is checked against the schema)

Configures the low-balance alert: while enabled and the balance sits below the threshold, an alert stays open and surfaces in the dashboard. Negative-balance alerts are always on. Requires an admin-role caller: an API key carries its creator's organization role, so the key must belong to an org admin.

## Request body

- SubscriptionUsageAlertSettingsUpdate: The usage-alert fields to change; an absent field keeps its current value.
  - `enabled` boolean: Whether low-balance alerts are active.
  - `threshold_microdollars` integer: Alert while the balance sits below this amount, in microdollars. Must be positive while enabled.

## Response `200`

OK

- SubscriptionUsageAlertSettingsResponse: The org's usage-alert configuration and any open alerts.
  - `active_alerts` SubscriptionActiveUsageAlert[], nullable, required: Currently open alerts, oldest first. Empty when the balance is healthy.
    - `balance_microdollars` integer, required: The balance when the alert opened, in microdollars. May be negative.
    - `kind` 'low_balance' | 'negative_balance', required: Which rule fired: the configurable low-balance threshold, or the balance going negative.
    - `threshold_microdollars` integer, required: The threshold in effect when the alert opened, in microdollars (0 for negative_balance).
    - `triggered_at` string, date-time, required: When the alert opened.
  - `enabled` boolean, required: Whether low-balance alerts are active. Negative-balance alerts are always on.
  - `threshold_microdollars` integer, required: Alert while the balance sits below this amount, in microdollars. Must be positive while enabled.

## Other responses

- `400`: Bad Request
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-10-24** `ecca093572e0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/billing/usage-alerts/patch.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)