---
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.

## 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 cap (null to remove)
  - `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 — Monthly overage cap in credits (null = unlimited)
  - `current_month_charged` number, required — Credits charged via overages this month
  - `current_month_start` string, required — ISO timestamp of current billing month start
  - `credit_limit` number, required — Plan's included credit allowance per period
  - `current_period_usage` number, required — Credits consumed in current billing period
  - `current_period_requests` integer — Number of inference requests in current billing period
  - `max_overage_hard_cap` number, nullable — Platform hard cap on daily overage spend in credits (null = no platform cap)
  - `paid_credit_balance` number — Persistent paid credit wallet balance (carries over indefinitely)
  - `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), regardless of plan reset interval.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pioneer/apis/brain-api.md) · [All operations](https://skmtc.net/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pioneer/brain-api/versions/31dfe831e079/schema)