Sample - GitHub REST API
PATCH/organizations/{org}/settings/billing/budgets/{budget_id}

Update an organization budget

Updates an existing budget for an organization. Supply the budget fields you want to change, including budget_amount, budget_scope, or prevent_further_usage, while preserving scope-specific constraints. The authenticated user must be an organization administrator or billing manager.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 parameters · 9 body fields
orgstringrequired
The organization name; matching is case-insensitive.
budget_idstringrequired
The identifier of the budget to update.

The budget properties to update for the organization.

budget_amountintegeroptional
The budget amount in whole dollars. For license-based products, this represents the number of licenses.
prevent_further_usagebooleanoptional
Whether to prevent additional spending once the budget is exceeded. For budgets with `user` or `multi_user_customer` scope, this must remain `true`.
budget_alertingobjectoptional
Alert settings for the budget; alerting is ignored for user scopes.
budget_scopestringoptional
The scope of the budget for this organization. - `organization`: Apply the budget to the organization. - `repository`: Apply the budget to a specific repository in the organization. - `multi_user_customer`: Apply a universal budget to all users in the organization. - `user`: Apply the budget to a single user in the organization.
Allowed:enterpriseorganizationrepositorycost_centermulti_user_customeruser
budget_entity_namestringoptional
The name of the entity to apply the budget to
budget_typestringoptional
The type of pricing model used by the budget. Determines how `budget_product_sku` is interpreted. - `BundlePricing`: Covers all AI credit SKUs. Set `budget_product_sku` to `ai_credits`. - `ProductPricing`: Covers all SKUs that belong to a product. Set `budget_product_sku` to a product such as `actions` or `packages`. - `SkuPricing`: Covers a single, specific SKU. Set `budget_product_sku` to a SKU such as `actions_linux`.
Allowed:BundlePricing
budget_product_skustringoptional
A single product or SKU that will be covered in the budget
userstringoptional
The username of the user for `user` scope budgets.
expires_atstringoptional
The date the budget will expire in `YYYY-MM-DD` format. Only dates in the future are accepted. If not set, the budget will not expire. Setting to `null` or `0` will remove the expiration date from a budget if set. Only supported for budgets with `budget_scope` of `user`

7 status codes
200Returns an object containing a result `message` and the updated `budget`, including its identifier, scope, amount, spending controls, product information, alert settings, and expiration date.
messagestringrequired
A message indicating the result of the update operation
budgetobjectrequired
400Returned when the request is invalid or a supplied budget value fails validation.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
401Returned when the request requires authentication that is missing or invalid.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
403Returned when the authenticated user is not authorized to update the budget.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
404Returned when the budget does not exist or the budget feature is not enabled.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
422Returned when validation fails or the endpoint has been spammed.
messagestringrequired
documentation_urlstringrequired
errorsarray<object>optional
500Returned when an internal server error occurs.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional

Error handling

A 400 is returned for an invalid request, a 401 when authentication is missing or invalid, and a 403 when the authenticated user lacks permission. A 404 is returned when the budget is not found or the feature is not enabled; a 422 indicates validation failure or endpoint abuse, and a 500 indicates an internal server error. budget_scope must be one of enterprise, organization, repository, cost_center, multi_user_customer, or user; expires_at accepts a future YYYY-MM-DD date or 0.