---
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 a member 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. ``custom_min_usd`` is the least a workspace may name for itself instead of picking one of ``bundles_usd``. There is no largest: one purchase is deliberately uncapped.
  - `bundles_usd` string[], required
  - `custom_min_usd` string, required
  - `can_purchase` boolean, required
  - `saved_card` SavedCardView, required — The card a purchase would charge, named so the page can show it. Absent when the workspace has no card saved, which is also the signal that buying has to collect one before it can charge.
    - `brand` string, required
    - `last4` string, 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 on an unattended charge: a higher cap cannot be saved, and a saved cap above a ceiling a later release lowers 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 a member clears by turning reload back on. The rest are derived and clear by themselves: a reactivated subscription, or a release restoring an amount, resumes a reload that was never turned off.
    - `enabled` boolean, required
    - `bundle_usd` string, nullable, required
    - `threshold_usd` string, nullable, required
    - `monthly_cap_usd` string, nullable, required
    - `max_monthly_cap_usd` string, 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' | 'usage_not_metered' | '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, a workspace moved off metered usage, 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-23** `7720763f8bf1` — 1 breaking, 2 warning, 6 info
  - removed the required property `automatic/offered` from the response with the `200` status
  - added the new `usage_not_metered` enum value to the `automatic/disabled_reason/anyOf[subschema #1: AutoReloadStopReason]/` response property for the response status `200`
  - added the new `usage_not_metered` enum value to the `code` response property for the response status `409`
  - removed the `auto_reload_not_offered` enum value from the `code` response property for the response status `409`
  - …5 more
- **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/7720763f8bf1?raw)