> ## Documentation Index > Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt > Use this file to discover all available pages before exploring further. # Set an organization's budget > Replaces the organization's budget; every field is required. A `billing.budget` notification is sent when the period's cost reaches `alert_threshold_percent` of `monthly_limit`, and again at the limit, once each per billing period. With `stop_at_limit`, reaching the limit also pauses new publishing for the organization's prod projects until the period ends; broadcasts already live continue. The change takes effect at once: a limit at or under the cost so far pauses now, and a pause ends as soon as the budget no longer stops. ## OpenAPI ````yaml /api-reference/openapi.yaml put /v1/organizations/{id}/budget openapi: 3.1.0 info: title: Qumo Deploy REST API description: > The Qumo Deploy control plane: organizations, projects, signing keys, machine identities, access control, audit and billing. Relay credentials are not issued here: your app signs them with its own [signing keys](/guides/signing-keys). Every operation here is generated against the routes the server registers and checked in CI, so an operation in this reference exists and a route missing from it is deliberately internal (relay mesh, webhooks, probes, operator-only and browser sign-in routes). Errors are JSON objects with one `error` field. What each status code means is in [Error codes](/guides/error-codes); the token scope each permission needs is in [Scopes and permissions](/guides/scopes-permissions). version: 1.0.0 servers: - url: https://api.qumo-deploy.com description: Public API (Bearer tokens only; cookies are ignored) security: [] tags: - name: Account description: The signed-in user's own sessions, tokens, security settings and data. - name: Device flow description: OAuth 2.0 device authorization, used by `qumod login`. - name: Organizations description: Organizations, their members and usage. - name: Projects description: Projects inside an organization. - name: Signing keys description: Keys your app signs relay credentials with. - name: Relays description: Where clients of a broadcast path connect. - name: Identities description: Machine identities, their tokens and IP allowlists. - name: Access control description: Roles, IAM bindings and invitations. - name: Audit description: The audit log and its webhook. - name: Notifications description: Notification policies. - name: Billing description: Plans, usage cost, budgets, invoices and payment methods. - name: Pricing description: Public price list. paths: /v1/organizations/{id}/budget: put: tags: - Billing summary: Set an organization's budget description: > Replaces the organization's budget; every field is required. A `billing.budget` notification is sent when the period's cost reaches `alert_threshold_percent` of `monthly_limit`, and again at the limit, once each per billing period. With `stop_at_limit`, reaching the limit also pauses new publishing for the organization's prod projects until the period ends; broadcasts already live continue. The change takes effect at once: a limit at or under the cost so far pauses now, and a pause ends as soon as the budget no longer stops. operationId: updateOrganizationBudget parameters: - name: id in: path required: true description: The organization ID. schema: type: string format: uuid example: 3f8c2a1e-7b4d-4e9a-9c61-2d5e8f0a1b7c requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationBudgetUpdate' responses: '200': description: The stored budget. content: application/json: schema: $ref: '#/components/schemas/OrganizationBudget' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - token: [] - cliSession: [] - sessionCookie: [] csrfToken: [] components: schemas: OrganizationBudgetUpdate: type: object description: The whole budget; every field is required. required: - monthly_limit - alert_threshold_percent - stop_at_limit properties: monthly_limit: type: number minimum: 0 maximum: 9999999999 description: Monthly limit in USD, rounded to cents; 0 removes the budget. example: 100 alert_threshold_percent: type: integer minimum: 1 maximum: 100 description: Percentage of `monthly_limit` at which the first alert is sent. example: 80 stop_at_limit: type: boolean description: >- Pause new publishing at the limit until the billing period ends. Needs a `monthly_limit` above 0. example: true OrganizationBudget: type: object required: - organization_id - monthly_limit - alert_threshold_percent - stop_at_limit - currency - period - cost_usd - publishing_paused_until - alerts properties: organization_id: type: string format: uuid example: 3f8c2a1e-7b4d-4e9a-9c61-2d5e8f0a1b7c monthly_limit: type: number description: Monthly limit in USD; 0 means no budget. example: 100 alert_threshold_percent: type: integer minimum: 1 maximum: 100 description: >- Percentage of `monthly_limit` at which the first alert is sent; the limit itself always alerts too. example: 80 stop_at_limit: type: boolean description: >- Whether reaching the limit pauses new publishing until the billing period ends. example: false currency: type: string enum: - USD example: USD updated_at: type: string format: date-time description: When the budget was last changed; omitted when none has been set. example: '2026-10-28T14:02:11Z' period: $ref: '#/components/schemas/BillingPeriod' cost_usd: type: number description: >- The period's cost so far, in USD before tax, priced as Stripe bills it. example: 42.18 publishing_paused_until: type: - string - 'null' format: date-time description: >- While the budget pauses publishing, when the pause ends (the end of the billing period); null otherwise. example: null alerts: type: array description: The alerts sent this billing period, newest first. items: $ref: '#/components/schemas/BudgetAlert' BillingPeriod: type: object description: | The billing period: the Stripe subscription's current period, or the calendar month (UTC) without one. required: - start - end properties: start: type: string format: date-time example: '2026-11-01T00:00:00Z' end: type: string format: date-time example: '2026-12-01T00:00:00Z' BudgetAlert: type: object required: - period_start - monthly_limit - threshold_percent - cost_usd - fired_at properties: period_start: type: string format: date-time description: Start of the billing period the alert was sent in. example: '2026-10-20T08:30:00Z' monthly_limit: type: number description: The limit in force when it was sent, in USD. example: 100 threshold_percent: type: integer description: The share of the limit reached; 100 is the limit itself. example: 80 cost_usd: type: number description: The period's cost when it was sent, in USD. example: 80.4 fired_at: type: string format: date-time example: '2026-10-27T03:00:00Z' Error: type: object required: - error properties: error: type: string description: A human-readable message. example: organization_id is required responses: BadRequest: description: >- Malformed request or failed validation. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Authenticated but not allowed (permission, token scope, IP allowlist or CSRF). See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- Not found, or not visible to the caller. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: token: type: http scheme: bearer bearerFormat: qumo_pat_ description: > A personal access token (`POST /v1/auth/tokens`) or a machine identity token (`POST /v1/projects/{project_id}/identities/{identity_id}/tokens`), both prefixed `qumo_pat_`. A token's scopes cap what it can do; see [Scopes and permissions](/guides/scopes-permissions). A personal token names no organization: on a route whose path names no project or organization, pass `?organization_id=`. cliSession: type: http scheme: bearer description: | The session token `qumod login` obtains through the device flow (`POST /v1/auth/device/token`). It acts as the signed-in user, like a console session, and needs no CSRF token. sessionCookie: type: apiKey in: cookie name: __Host-qumo_session description: | The console's browser session. Accepted only on the console origin (`https://console.qumo-deploy.com`), never on `api.qumo-deploy.com`. A request that changes state must also send `X-CSRF-Token`. csrfToken: type: apiKey in: header name: X-CSRF-Token description: | CSRF token paired with `sessionCookie` on POST, PUT, PATCH and DELETE. Bearer requests do not send it. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.