Sign in
billing

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

patch/billing/team/{team_id}/overage-settings

Path parameters

team_idstring required

Request body

overage_enabledboolean nullable
topup_amountnumber nullable

Credits per top-up (100 = $1)

topup_modestring nullable

Top-up mode: 'by' or 'to'

charge_thresholdnumber nullable

Remaining credits trigger

max_monthly_spendnumber nullable

Monthly auto-refill cap in credits (null uses platform default)

usage_reset_hourinteger nullable

Local hour for daily reset. Must be between 0 and 23.

usage_reset_timezonestring nullable

IANA timezone used to interpret usage_reset_hour.

Response

Successful Response

overage_enabledboolean required
topup_amountnumber required

Credits added per top-up charge (1 credit = $0.01)

topup_modestring

Top-up mode: 'by' adds a fixed amount, 'to' restores balance to topup_amount

charge_thresholdnumber required

Trigger charge when remaining credits drop below this

max_monthly_spendnumber nullable required

Optional per-team monthly auto-refill cap in credits (null uses platform default)

effective_monthly_capnumber 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_chargednumber required

Credits charged via overages this month

current_month_startstring required

ISO timestamp of current billing month start

usage_reset_hourinteger

Local hour when daily credits reset. 0-23 in usage_reset_timezone.

usage_reset_timezonestring

IANA timezone used to interpret usage_reset_hour.

usage_reset_hour_changed_atstring nullable

ISO timestamp of last reset-hour change. Null if never changed.

today_usagenumber

Credits consumed since midnight today in the team's usage_reset_timezone (falls back to UTC for invalid timezone names).

Changes