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 Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/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
Exampleupdate-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 typeapplication/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
Exampleupdate-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
Examplegenerated
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

401

Section titled “401”

Requires authentication

Media typeapplication/json
Basic Error

Basic Error

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

403

Section titled “403”

Forbidden

Media typeapplication/json
Basic Error

Basic Error

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

404

Section titled “404”

Budget not found or feature not enabled

Media typeapplication/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 typeapplication/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
Examplegenerated
{
  "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 typeapplication/json
Basic Error

Basic Error

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