billing

Create a budget

Changed on

Creates a new budget for an enterprise. Enterprise owners and billing managers can create budgets scoped to the enterprise, all users in the enterprise, or any organization in it. Organization administrators can create budgets for their organizations, and repository-scoped budgets require administration of the repository's owning organization. A custom role holder with fine-grained write access to enterprise billing can create budgets scoped to a single user or a cost center, including all users in a cost center, without an additional administrator role; the role requirements above still apply to the other scopes. An installation access token for a GitHub App installed on the enterprise with write access to enterprise billing can create budgets for any target in the enterprise.

post/enterprises/{enterprise}/settings/billing/budgets

Request

  • Base URL: https://api.github.com
  • URL: https://api.github.com/enterprises/{enterprise}/settings/billing/budgets
  • Auth: none declared

Path parameters

enterprisestring required

The slug version of the enterprise name.

Request body

budget_amountinteger required

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

prevent_further_usageboolean required

Whether to prevent additional spending once the budget is exceeded. For user and multi_user_customer scopes, this must be true.

budget_scope'enterprise' | 'organization' | 'repository' | 'cost_center' | 'multi_user_customer' | 'multi_user_cost_center' | 'user' required

The scope of the budget.

  • enterprise: Apply the budget to the entire enterprise.
  • organization: Apply the budget to a specific organization in the enterprise.
  • repository: Apply the budget to a specific repository.
  • cost_center: Apply the budget to a specific cost center.
  • multi_user_customer: Apply a universal budget to all users in the enterprise.
  • multi_user_cost_center: Apply a universal budget to all users in a cost center.
  • user: Apply the budget to a single user.

user, multi_user_customer, and multi_user_cost_center scopes are only supported when budget_product_sku is ai_credits or premium_requests.

budget_entity_namestring

The name of the entity to apply the budget to

budget_product_skustring

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

userstring

The username of the user for user scope budgets. This field is required when budget_scope is user.

expires_atstring date

The date the budget will expire in YYYY-MM-DD format. Only dates in the future are accepted. If not provided, the budget will not expire.

Only supported for budgets with budget_scope of user

Response

Budget created successfully

messagestring required

A message indicating the result of the create operation

Example response

{
  "budget": {
    "budget_scope": "enterprise",
    "budget_entity_name": "example-repository-name",
    "budget_amount": 100,
    "prevent_further_usage": true,
    "budget_product_sku": "actions_linux",
    "budget_alerting": {
      "will_alert": true,
      "alert_recipients": [
        "mona",
        "lisa"
      ]
    },
    "expires_at": "2026-12-31"
  }
}

Changes

  • 2022-11-28cb7b1b79509eRevision changes
    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

  • 2022-11-28ff40e51c67d0Revision changes
    • warning

      added the new multi_user_cost_center enum value to the / response property for the response status

    • info

      added the new multi_user_cost_center enum value to the request property