---
title: "Set or clear account spend and balance controls"
method: PUT
path: "/credits/tenants/me/spend-controls"
tags: ["Tenants"]
---

# Set or clear account spend and balance controls

`PUT /credits/tenants/me/spend-controls`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/credits/tenants/me/spend-controls`
- Auth: HTTP bearer

Sets the monthly hard ceiling, monthly spend-email threshold, and/or low-balance email threshold. Send at least one field; omitted fields keep their current value and an explicit null clears one. Amounts are positive USD with at most 6 decimal places, up to 1000000000, and alertThresholdUsd may not exceed monthlyLimitUsd. Once committed spend reaches the ceiling, burns are denied with TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED until the window resets — the limit bounds new spend and never cancels in-flight calls. Personal changes require the account owner on a session authenticated within the last ten minutes; enterprise changes require a workspace owner or admin with MFA or passkey step-up in that window.

## Headers

- `X-Locus-Step-Up` string, password

## Request body

- object
  - `monthlyLimitUsd` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
  - `alertThresholdUsd` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
  - `lowBalanceAlertUsd` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.

## Response `200`

Updated controls

- object
  - `success` unknown, required
  - `controls` WorkspaceSpendControls, required: Account-wide monthly spend controls and low-balance notification state, plus the live position in the current UTC month window. Available to Personal and enterprise accounts. Amounts are exact USD decimal strings.
    - `periodStart` string, date-time, required: Start of the current UTC calendar-month window.
    - `periodEnd` string, date-time, required: When the window resets.
    - `spentUsd` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `pendingUsd` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `committedUsd` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `remainingUsd` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `monthlyLimitUsd` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `alertThresholdUsd` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `lowBalanceAlertUsd` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `lowBalanceAlertSentAt` string, date-time, nullable, required: When the current low-balance crossing was emailed. null while armed; it returns to null after the balance recovers above the threshold.
    - `hardLimitReached` boolean, required: true once committedUsd reaches monthlyLimitUsd. Further burns are denied with TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED until the window resets.
    - `alert` object, required
      - `status` 'pending' | 'sent' | 'failed' | 'null', nullable, required
      - `triggeredAt` string, date-time, nullable, required
      - `sentAt` string, date-time, nullable, required
      - `lastError` string, nullable, required

## Other responses

- `400`: Unknown field, no field supplied, a non-positive or over-precise amount, or an alert threshold above the limit.
- `403`: RECENT_AUTHENTICATION_REQUIRED or OWNER_REQUIRED for a Personal account; STEP_UP_REQUIRED for an enterprise owner/admin without recent MFA/passkey step-up or for a non-workspace-administrator principal; or INSUFFICIENT_SCOPE.

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)