Skip to content
forgit api docs

Update a budget for an organization

PATCH
/organizations/{org}/settings/billing/budgets/{budget_id}

Updates an existing budget for an organization. The authenticated user must be an organization admin or billing manager.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

budget_id
required
string

The ID corresponding to the budget.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
budget_amount

The budget amount in whole dollars. For license-based products, this represents the number of licenses.

integer
prevent_further_usage

Whether to prevent additional spending once the budget is exceeded. For budgets with user or multi_user_customer scope, this must remain true.

boolean
budget_alerting
object
will_alert

Whether alerts are enabled for this budget

boolean
alert_recipients

Array of user login names who will receive alerts

Array<string>
budget_scope

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.
string
Allowed values: enterprise organization repository cost_center multi_user_customer user
budget_entity_name

The name of the entity to apply the budget to

string
budget_type
One of:
string
Allowed values: BundlePricing
budget_product_sku

A single product or SKU that will be covered in the budget

string
user

The username of the user for user scope budgets.

string
Examples
Example update-budget

Update budget example 

{
  "prevent_further_usage": false,
  "budget_amount": 10,
  "budget_alerting": {
    "will_alert": false,
    "alert_recipients": []
  }
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Budget updated successfully

Media type application/json
object
message
required

A message indicating the result of the update operation

string
budget
required
object
id

ID of the budget.

string
budget_scope

The type of scope for the budget

string
Allowed values: enterprise organization repository cost_center multi_user_customer multi_user_cost_center user
budget_entity_name

The name of the entity to apply the budget to

string
user

The user login when the budget is scoped to a single user (user scope).

string
consumed_amount

The consumed amount for the specified user within the budget. Only included for user-scoped budgets.

number
budget_amount

The budget amount in whole dollars. For license-based products, this represents the number of licenses.

integer
prevent_further_usage

Whether to prevent additional spending once the budget is exceeded

boolean
budget_product_sku

A single product or sku to apply the budget to.

string
budget_type
One of:
string
Allowed values: ProductPricing
budget_alerting
object
will_alert

Whether alerts are enabled for this budget

boolean
alert_recipients

Array of user login names who will receive alerts

Array<string>
Examples
Example update-budget 
{
  "message": "Budget successfully updated.",
  "budget": {
    "id": "2066deda-923f-43f9-88d2-62395a28c0cdd",
    "budget_type": "ProductPricing",
    "budget_product_sku": "actions_linux",
    "budget_scope": "repository",
    "budget_entity_name": "org-name/example-repo-name",
    "budget_amount": 10,
    "prevent_further_usage": true,
    "budget_alerting": {
      "will_alert": true,
      "alert_recipients": [
        "mona",
        "lisa"
      ]
    }
  }
}

400

Section titled “ 400 ”

Bad Request

Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

401

Section titled “ 401 ”

Requires authentication

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

403

Section titled “ 403 ”

Forbidden

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

404

Section titled “ 404 ”

Budget not found or feature not enabled

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Examples
{
  "message": "Budget with ID 550e8400-e29b-41d4-a716-446655440000 not found.",
  "documentation_url": "https://docs.github.com/rest/billing/budgets#update-a-budget"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error

Validation Error

object
message
required
string
documentation_url
required
string
errors
Array<object>
object
resource
string
field
string
message
string
code
required
string
index
integer
value
One of:
string
nullable
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}

500

Section titled “ 500 ”

Internal server error

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Examples
Example server-error 
{
  "message": "Unable to update budget.",
  "documentation_url": "https://docs.github.com/rest/billing/budgets#update-a-budget"
}