---
title: "Update team overage settings"
method: PATCH
path: "/billing/team/{team_id}/overage-settings"
tags: ["billing"]
---

# Update team overage settings

`PATCH /billing/team/{team_id}/overage-settings`

Update overage billing configuration. Requires MANAGE_BILLING.

Auto-refill is how a team keeps its wallet funded, so no plan tier decides
whether it may be enabled — a team on ``free`` is the one most likely to run
dry, and refusing it here is what invariant 14 of the prepaid ledger design
forbids ("the ability to spend depends only on funds, limits, and payment
health"). Whether a refill can actually be charged is a payment-method
question, answered by Stripe at charge time, not a subscription question.

Args:
    team_id: Team whose settings are being updated.
    request: Fields to change; unset fields are left alone.
    auth: Caller identity; must hold MANAGE_BILLING on the team.

Returns:
    The team's settings after the update.

Raises:
    HTTPException: 403 without MANAGE_BILLING on the team; 404 if the team
        does not exist; 400 for any validation failure below — an invalid
        ``topup_mode``, a reset-window change the plan disallows, a null or
        invalid ``usage_reset_hour`` / ``usage_reset_timezone``, or a request
        that sets no fields.

## Path parameters

- `team_id` string, required

## Request body

- UpdateOverageSettingsRequest — Request to update overage billing settings.
  - `overage_enabled` boolean, nullable
  - `topup_amount` number, nullable — Credits per top-up (100 = $1)
  - `topup_mode` string, nullable — Top-up mode: 'by' or 'to'
  - `charge_threshold` number, nullable — Remaining credits trigger
  - `max_monthly_spend` number, nullable — Monthly auto-refill cap in credits (null uses platform default)
  - `usage_reset_hour` integer, nullable — Local hour for daily reset. Must be between 0 and 23.
  - `usage_reset_timezone` string, nullable — IANA timezone used to interpret usage_reset_hour.

## Response `200`

Successful Response

- OverageSettingsResponse — Current overage billing settings for a team.
  - `overage_enabled` boolean, required
  - `topup_amount` number, required — Credits added per top-up charge (1 credit = $0.01)
  - `topup_mode` string — Top-up mode: 'by' adds a fixed amount, 'to' restores balance to topup_amount
  - `charge_threshold` number, required — Trigger charge when remaining credits drop below this
  - `max_monthly_spend` number, nullable, required — Optional per-team monthly auto-refill cap in credits (null uses platform default)
  - `effective_monthly_cap` number, required — The monthly auto-refill cap actually enforced, in credits: the team's max_monthly_spend when it has selected one, and the platform default otherwise. Always populated, so a client never has to infer the ceiling in force from a null max_monthly_spend.
  - `current_month_charged` number, required — Credits charged via overages this month
  - `current_month_start` string, required — ISO timestamp of current billing month start
  - `usage_reset_hour` integer — Local hour when daily credits reset. 0-23 in usage_reset_timezone.
  - `usage_reset_timezone` string — IANA timezone used to interpret usage_reset_hour.
  - `usage_reset_hour_changed_at` string, nullable — ISO timestamp of last reset-hour change. Null if never changed.
  - `today_usage` number — Credits consumed since midnight today in the team's usage_reset_timezone (falls back to UTC for invalid timezone names).

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-24** `1cffaad2a921` — 2 breaking, 4 warning, 2 info
  - removed the required property `credit_limit` from the response with the `200` status
  - removed the required property `current_period_usage` from the response with the `200` status
  - removed the optional property `current_period_requests` from the response with the `200` status
  - removed the optional property `detail` from the response with the `422` status
  - …4 more

[Change history](https://skmtc.dev/pioneer/apis/brain-api/changes/billing/team/:team_id/overage-settings/patch.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) · [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/1cffaad2a921?raw)