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

# Update usage-alert settings

`PATCH /billing/usage-alerts`

## Request

- Base URL: `/api/v1` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v1/billing/usage-alerts`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api/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.
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `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.
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `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-23** `49b1da5a7974`: 1 info
  - endpoint added

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

---

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