---
title: "Update auto-recharge settings"
method: PATCH
path: "/billing/auto-recharge"
tags: ["billing"]
---

# Update auto-recharge settings

`PATCH /billing/auto-recharge`

## 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/auto-recharge`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api/docs/billing/auto-recharge/patch.ts> (a function with typed inputs; its response is checked against the schema)

Configures automatic balance top-up: when the balance drops below the threshold, a one-off invoice charges the saved payment method to restore it to the target. Requires an admin-role caller: an API key carries its creator's organization role, so the key must belong to an org admin. This only tunes when the saved payment method is charged — adding funds or payment methods stays in the dashboard.

## Request body

- SubscriptionAutoRechargeSettingsUpdate: The auto-recharge 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 auto-recharge is active. Enabling clears any prior payment-failure auto-disable.
  - `target_microdollars` integer: Balance the recharge restores to, in microdollars (minimum 5_000_000 = $5.00 while enabled).
  - `threshold_microdollars` integer: Recharge when the balance drops below this amount, in microdollars.

## Response `200`

OK

- SubscriptionAutoRechargeSettingsResponse: The org's auto-recharge configuration and status.
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `disabled_reason` 'payment_failed' | 'disputed': Why auto-recharge turned itself off, if it did: payment_failed (a recharge payment failed for good) or disputed (a payment was disputed). Re-enabling clears it.
  - `enabled` boolean, required: Whether auto-recharge is active.
  - `in_flight` SubscriptionAutoRechargeAttempt: A recharge being collected: pending payment, or declined and retrying.
    - `amount_microdollars` integer, required: Credit the recharge adds once paid, in microdollars.
    - `failed_attempts` integer, required: How many payment attempts failed so far.
    - `last_error` string: Why the last payment attempt failed (for example, the card was declined), when known.
    - `next_attempt_at` string, date-time: When Stripe will try the payment again, while retrying.
    - `started_at` string, date-time, required: When the recharge was started.
    - `state` 'pending' | 'retrying', required: pending: the recharge invoice is waiting to be paid. retrying: a payment attempt failed and Stripe will try again.
  - `target_microdollars` integer, required: Balance the recharge restores to, in microdollars (minimum 5_000_000 = $5.00). The charge is target minus current balance.
  - `threshold_microdollars` integer, required: Recharge when the balance drops below this amount, in microdollars.

## 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/auto-recharge/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)