Update Budget

PATCH /budgets/{budget_id}

Update Budget

Update a budget's name, limit, period, or enforcement mode. Fields left out keep their current values. The budget's scope and scope_ref are fixed at creation — to cap a different target, create a new budget.

Parameters

• budget_id (path, string, required): Budget ID.

Request body

Content type: application/json

• display_name (string, optional): New budget name.

• limit_cents (integer, optional): New spending limit in USD cents.

• period (string, optional): Calendar window the limit applies to, in UTC: day resets at 00:00, week on Monday 00:00, month on the 1st at 00:00.

• hard_stop (boolean, optional): New enforcement mode.

• alert_thresholds (array, optional): New percent-of-limit alert points. Omitted keeps the current value; explicit null resets to the default ([80]).

Responses

• 200: OK

• budget (object, required): A spending cap on one target. Amounts are integer USD cents.

• budget.id (string, required): Budget ID.

• budget.org_id (string, required): Organization that owns this budget.

• budget.scope (string, required): What a budget's spend counts. org caps the whole organization. environment caps one environment. api_key caps one caller API key and provider_key one upstream credential. team is a pool shared by every caller API key bound to the team. member is organization-wide for one member: all caller API keys bound to that member, in any team. team_member gives every member of one team an individual allowance of the same size, counting only their spend through keys bound to both that team and that member.

• budget.scope_ref (string, required): ID of the target the budget applies to, matching scope: an environment ID, caller API key ID, provider key ID, team ID, or member ID. team_member budgets reference a team ID. For org budgets this holds the organization's internal ID, which differs from the organization identifier used elsewhere in this API. Fixed at creation.

• budget.display_name (string, required): Human-readable budget name.

• budget.limit_cents (integer, required): Spending limit in USD cents.

• budget.period (string, required): Calendar window the limit applies to, in UTC: day resets at 00:00, week on Monday 00:00, month on the 1st at 00:00.

• budget.hard_stop (boolean, required): Whether the gateway rejects matching traffic with 429 budget_exceeded once the period's spend reaches the limit. When false the budget only reports the over-limit state.

• budget.alert_thresholds (array, optional): Percent-of-limit points at which a budget_threshold notification fires once per period, delivered to the organization's enabled notification channels. null means the default ([80]). Values above 100 fire under either enforcement mode and flag overspend: hard_stop rejects new requests once the control plane observes spend at the limit, but it does not cap the cost of requests already admitted, so a hard-stopped budget can settle above 100.

• budget.created_at (string, required): Time when the budget was created.

• budget.updated_at (string, required): Time when the budget was last updated.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to PATCH /budgets/{budget_id}, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to PATCH /budgets/{budget_id}, response 400 above.

cURL

curl -X PATCH '$AISIX_CP/budgets/{budget_id}' -H 'Authorization: Bearer $AISIX_TOKEN'