> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt > Use this file to discover all available pages before exploring further. # Set or clear account spend and balance controls > 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 the workspace owner with MFA or passkey step-up in that window. ## OpenAPI ````yaml /api-reference/openapi.json put /credits/tenants/me/spend-controls openapi: 3.1.0 info: title: Locus Pro API description: >- Production is live at https://api.paywithlocus.com/api. Stage remains available for evaluation and integration testing at https://api.stage.paywithlocus.com/api; credentials, balances, and tenant data are isolated by environment. Embedded prepaid credits over the Locus pay-per-use catalog. Money and top-up amounts use exact decimal strings (up to 6dp). Every burn requires an Idempotency-Key header. Management routes accept a tenant secret key or authorized dashboard session as shown per operation. Widget routes accept an end-user JWT alone; when a publishable key is present it must belong to the JWT's tenant. MCP uses OAuth 2.1 Authorization Code with PKCE by default and also accepts the explicitly documented tenant secret key, end-user JWT, or scoped agent connection compatibility credentials. Burns accept the execution credentials shown per operation. Publishable keys never authorize management or burns by themselves. version: 0.6.0 servers: - url: https://api.paywithlocus.com/api description: Production - url: https://api.stage.paywithlocus.com/api description: Stage — evaluation and integration testing security: - secretKey: [] tags: - name: Authentication description: Email-verified self-serve account creation and dashboard identity - name: Tenants description: Tenant profile, keys, and settings (dashboard session or secret key) - name: Workspace members description: Invite-only human workspace membership and role administration - name: Catalog description: Enable/disable APIs and set markups - name: Custom APIs description: >- Available when enabled for the workspace. Enterprise BYOK providers and schema-backed custom actions - name: End users description: End-user accounts, tokens, and allocations - name: Top-ups description: Locus-hosted checkout top-ups and quotes - name: Ledger description: Burn/top-up history and earnings - name: Webhooks description: Signed events, delivery inspection, and replay - name: Burn description: Metered pay-per-use calls - name: Travel routing description: >- Available when enabled for the workspace. Multi-provider flight search, no-dispatch planning, and feedback - name: MCP description: Stateless Streamable HTTP transport and MCP tool-result contracts - name: Okibi Identity description: >- Available when enabled for the workspace. Okibi identity verification and scoped native CLI credential bootstrap - name: Widget description: End-user JWT surface; a matching publishable key is optional - name: Agent-native onboarding description: >- Self-registration, human Stripe funding handoff, and restricted account setup for headless agents - name: Agent connections description: Scoped, expiring, revocable credentials for agent execution - name: Capability routing description: Outcome-level web search and research across eligible catalog providers paths: /credits/tenants/me/spend-controls: put: tags: - Tenants summary: Set or clear account spend and balance controls description: >- 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 the workspace owner with MFA or passkey step-up in that window. requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: monthlyLimitUsd: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' description: Hard monthly ceiling, or null to remove it. alertThresholdUsd: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' description: >- Monthly spend email trigger, or null to remove it. Lowering it below current spend triggers the alert immediately. lowBalanceAlertUsd: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' description: >- Remaining prepaid-balance threshold for a one-time email, or null to remove it. The alert re-arms after the balance recovers above the threshold. additionalProperties: false examples: setBoth: summary: Cap at $5,000 and alert at $4,000 value: monthlyLimitUsd: '5000.00' alertThresholdUsd: '4000.00' clearLimit: summary: Remove the hard cap, keep the alerts value: monthlyLimitUsd: null setLowBalanceAlert: summary: Email when the remaining balance reaches $10 value: lowBalanceAlertUsd: '10.00' responses: '200': description: Updated controls content: application/json: schema: type: object required: - success - controls properties: success: const: true controls: $ref: '#/components/schemas/WorkspaceSpendControls' additionalProperties: false '400': description: >- Unknown field, no field supplied, a non-positive or over-precise amount, or an alert threshold above the limit. '403': description: >- RECENT_AUTHENTICATION_REQUIRED or OWNER_REQUIRED for a Personal account; STEP_UP_REQUIRED for an enterprise owner without recent MFA/passkey step-up; or INSUFFICIENT_SCOPE. security: - dashboardSession: [] components: schemas: DecimalString: type: string pattern: ^\d+(?:\.\d{1,6})?$ description: >- Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply. WorkspaceSpendControls: type: object description: >- 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. additionalProperties: false required: - periodStart - periodEnd - spentUsd - pendingUsd - committedUsd - remainingUsd - monthlyLimitUsd - alertThresholdUsd - lowBalanceAlertUsd - lowBalanceAlertSentAt - hardLimitReached - alert properties: periodStart: type: string format: date-time description: Start of the current UTC calendar-month window. periodEnd: type: string format: date-time description: When the window resets. spentUsd: allOf: - $ref: '#/components/schemas/DecimalString' description: Captured spend in this window. pendingUsd: allOf: - $ref: '#/components/schemas/DecimalString' description: Held but not yet captured (in-flight calls). committedUsd: allOf: - $ref: '#/components/schemas/DecimalString' description: spentUsd plus pendingUsd — the figure checked against the limit. remainingUsd: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' description: null when no monthly limit is set. monthlyLimitUsd: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' description: Hard ceiling. null means unlimited. alertThresholdUsd: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' description: Monthly spend email trigger. null means no alert. lowBalanceAlertUsd: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' description: Remaining prepaid-balance email trigger. null means no alert. lowBalanceAlertSentAt: type: - string - 'null' format: date-time description: >- When the current low-balance crossing was emailed. null while armed; it returns to null after the balance recovers above the threshold. hardLimitReached: type: boolean description: >- true once committedUsd reaches monthlyLimitUsd. Further burns are denied with TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED until the window resets. alert: type: object additionalProperties: false required: - status - triggeredAt - sentAt - lastError properties: status: type: - string - 'null' enum: - pending - sent - failed - null triggeredAt: type: - string - 'null' format: date-time sentAt: type: - string - 'null' format: date-time lastError: type: - string - 'null' securitySchemes: secretKey: type: http scheme: bearer description: Tenant secret key (lcr_…). Server-side only. dashboardSession: type: http scheme: bearer description: Locus Pro dashboard session (Cognito). ````