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

Create a budget for an organization

Creates a budget for an organization. Use budget_scope, budget_amount, and budget_product_sku to define what the budget covers; user is required when the scope is user, and expires_at is supported only for user-scoped budgets. The authenticated user must be an organization admin or billing manager.

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

1 parameter · 9 body fields
orgstringrequired
The organization name. The name is not case sensitive.

Organization budget settings. 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 `user` and `multi_user_customer` scopes, this must be `true`.
budget_alertingobjectoptional
Alert settings, including whether alerts are enabled with `will_alert` and the user login names to notify in `alert_recipients`. Alerting fields are rejected for `user` scope budgets.
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 message and the created budget, including its identifier, scope, amount, usage controls, product or SKU, alert settings, and expiration date.
messagestringrequired
A message indicating the result of the create 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 organization 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 organization 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. budget_scope must be one of organization, repository, multi_user_customer, or user; budget_type must be BundlePricing, ProductPricing, or SkuPricing, and user is required for the user scope. prevent_further_usage must be true for user and multi_user_customer scopes; expires_at must be a future date in YYYY-MM-DD format and is only supported for user scope, while alerting fields are rejected for that scope. The org path parameter must identify an organization, and the authenticated user must be an organization admin or billing manager.