---
title: "Update Automatic Reload"
method: PUT
path: "/api/v1/billing/reloads/automatic"
tags: ["billing"]
---

# Update Automatic Reload

`PUT /api/v1/billing/reloads/automatic`

Turn automatic reload on or off.

Turning it on is refused unless the workspace has an active paid plan with
no cancel pending, a saved card, an approved bundle, a threshold above
zero, and a monthly cap at least that bundle and at most MAIA's maximum.
Turning it off always succeeds.

## Request body

- AutomaticReloadUpdateRequest — Turn automatic reload on or off. The three amounts travel together: all of them or none. Turning it on needs them. Turning it off without them keeps what was stored, so re-enabling is one request. Those rules are answered by ``settled()`` rather than by field constraints and a validator, because each one is broken by what an admin types into the reload form: a rule enforced here answers 422 carrying no refusal code, and the form can then state only that nothing was saved.
  - `enabled` boolean, required
  - `bundle_usd` union
    - number
    - string
  - `threshold_usd` union
    - number
    - string
  - `monthly_cap_usd` union
    - number
    - string

## Response `200`

Successful Response

- ReloadSettingsResponse — What the billing page needs to show and change reloads.
  - `bundles_usd` string[], required
  - `can_purchase` boolean, required
  - `confirmable_attempt_id` string, uuid, nullable, required
  - `automatic` AutomaticReloadView, required — A workspace's automatic reload, with the platform terms it runs under. ``threshold_usd`` and ``monthly_cap_usd`` are the workspace's own choices. ``max_monthly_cap_usd`` is MAIA's ceiling: a higher cap cannot be saved, and a saved cap above a later-lowered ceiling is charged against the ceiling. ``disabled_reason`` names the one thing stopping automatic reload from charging, whether or not ``enabled`` is still true. Only the payment reasons are stored pauses an admin clears by turning reload back on. The rest are derived and clear by themselves: a reactivated subscription, or staff restoring a bundle or maximum, resumes a reload that was never turned off.
    - `enabled` boolean, required
    - `offered` boolean, required
    - `bundle_usd` string, nullable, required
    - `threshold_usd` string, nullable, required
    - `monthly_cap_usd` string, nullable, required
    - `max_monthly_cap_usd` string, nullable, required
    - `spent_this_period_usd` string, required
    - `period_end` string, date, nullable, required
    - `disabled_reason` 'subscription_cancel_requested' | 'payment_failed' | 'authentication_required' | 'no_saved_payment_method' | 'no_paid_plan' | 'subscription_inactive' | 'not_offered' | 'bundle_withdrawn' | 'cap_below_bundle', required — Why a workspace's automatic reload will not charge, as its admins see it. The stored pauses, plus the conditions that stop an enabled reload without anyone turning it off: a pending cancel, a lapsed subscription, and terms staff changed after the workspace saved its own.
  - `latest_attempts` ReloadAttemptView[], required
    - `id` string, uuid, required
    - `trigger` 'manual' | 'automatic', required — Who started a reload.
    - `status` 'pending' | 'requires_action' | 'succeeded' | 'failed' | 'canceled', required — Where one attempt stands, as read back from its PaymentIntent.
    - `amount_usd` string, required
    - `failure_code` 'authentication_required' | 'card_declined' | 'no_saved_payment_method' | 'not_charged' | 'payment_failed', required — Why an attempt ended without collecting, in customer-actionable terms.
    - `created_at` string, date-time, required
    - `resolved_at` string, date-time, nullable, required

## Other responses

- `409` — Conflict
- `422` — Validation Error
- `503` — Service Unavailable

## Changes

- **2026-09-19** `924eeadc29ad` — 5 warning, 1 info
  - the `bundle_usd/anyOf[subschema #1]/` request property's min was set to `0.00`
  - the `monthly_cap_usd/anyOf[subschema #1]/` request property's min was set to `0.00`
  - the `threshold_usd/anyOf[subschema #1]/` request property's min was set to `0.00`
  - added the new `amount_not_positive` enum value to the `code` response property for the response status `409`
  - …2 more
- **2026-09-18** `73f618ba0a7e` — 1 warning
  - added the new `price_not_found` enum value to the `code` response property for the response status `503`
- **2026-09-16** `95495ef535bc` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/billing/reloads/automatic/put.md)

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/maia-analytics/apis/maia-api/revisions/924eeadc29ad?raw)