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

Create a budget for an organization

Creates a new budget for an organization. Supply the budget scope, amount, pricing information, and any applicable alerting or expiration settings; the authenticated user must be an organization administrator or billing manager. Use budget_entity_name to target a repository or user when the selected scope requires a specific entity.

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

1 parameter · 9 body fields
orgstringrequired
The organization name to create the budget for; the name is not case sensitive.

Optional organization budget configuration, including scope, amount, pricing, alerting, target entity, and expiration settings.

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 `user` and `multi_user_customer` scopes, this must be `true`.
budget_alertingobjectoptional
Alert configuration containing `will_alert` and `alert_recipients`; alerting is rejected for user scope because it is always disabled.
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. `user` and `multi_user_customer` scopes are only supported when `budget_product_sku` is `ai_credits` or `premium_requests`.
Allowed:organizationrepositorymulti_user_customeruser
budget_entity_namestringoptional
The name of the entity to apply the budget to
Default:
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. This field is required when `budget_scope` is `user`.
expires_atstringoptional
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`

7 status codes
200Returns a result object containing a creation message and the created budget, including its identifier, scope, amount, spending controls, product SKU, alerting configuration, and expiration date.
messagestringrequired
A message indicating the result of the create operation
budgetobjectrequired
400Returned when the request is malformed or contains invalid budget configuration.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
401Returned when authentication is required.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
403Returned when the authenticated user lacks permission to create budgets for the organization.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
404Returned when the budgeting feature is not enabled or the organization does not exist.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
422Returned when budget 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 a malformed request, a 401 when authentication is required, a 403 when the authenticated user lacks permission, a 404 when the feature is not enabled or the organization is not found, a 422 when validation fails or the endpoint has been spammed, and a 500 for an internal server error. budget_scope must be one of: organization, repository, multi_user_customer, or user, and budget_type must be BundlePricing, ProductPricing, or SkuPricing. user is required for the user scope, prevent_further_usage must be true for user and multi_user_customer scopes, and expires_at must be a future date in YYYY-MM-DD format when supplied.