GitHub API (unofficial showcase)
PATCH/organizations/{org}/settings/billing/budgets/{budget_id}

Update a budget for an organization

Updates an existing budget for an organization. Supply the budget fields you want to change; expiration updates are supported only for existing user-scoped budgets, and setting expires_at to 0 removes the expiration date. The authenticated user must be an organization admin or billing manager.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 4 body fields
orgstringrequired
The organization name. The name is not case sensitive.
budget_idstringrequired
The identifier of the budget to update.

Budget fields to update. All fields are optional.

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, including whether alerts are enabled with `will_alert` and the user login names to notify in `alert_recipients`. These settings are ignored for user-scoped 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 existing user-scoped budgets.

7 status codes
200Returns a message and the updated budget, including its identifier, scope, amount, consumed amount, usage controls, product or SKU, alert settings, and expiration date.
messagestringrequired
A message indicating the result of the update operation
budgetobjectrequired
400Returned when the request is invalid.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
401Returned when authentication is required.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
403Returned when the authenticated user does not have sufficient permissions.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
404Returned when the budget is not found or the 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 indicates a bad request; a 401 is returned when authentication is required; a 403 indicates insufficient permissions; a 404 is returned when the budget is not found or the feature is not enabled; a 422 indicates validation failure or that the endpoint has been spammed; a 500 indicates an internal server error. expires_at must be a future date in YYYY-MM-DD format or 0 to remove the expiration date, and date values are supported only for existing user-scoped budgets; prevent_further_usage must remain true for budgets with user or multi_user_customer scope. The org path parameter must identify an organization, the budget_id path parameter must identify a budget, and the authenticated user must be an organization admin or billing manager.