billing.budgets.create

Create a budget

POST /billing/api/budgetsIAM billing:CreateBudgetChanges state

Request syntax

POST /billing/api/budgets
{
  "name": "string",
  "amountCents": "number",
  "period": "enum",
  "scope": "object",
  "serviceFilter": "array of string",
  "alertThresholds": "array of number",
  "notificationEmails": "array of string",
  "action": "object",
  "forecastThresholds": "array of number"
}

Request body

  • nameRequired

    string

    1–255 characters; need not be unique

    Constraints: 1-255 chars

  • amountCentsRequired

    number

    The cap in euro cents (net, before VAT), a positive whole number: 50000 is €500

    Constraints: integer, min 1

  • periodRequired

    enum

    monthly, quarterly or annual; required here (the console’s form starts at monthly). Periods start at midnight German time, like the invoice

    One of: monthly, quarterly, annual

  • scopeOptional

    object

    What the budget counts: {type: organization}, {type: resourceProject, projectId} (a project), {type: project, projectId} (a saved tag view) or {type: tags, clauses}. A resource without the scope’s tags is not counted. A project that does not exist is accepted and reported as a broken scope. Default: the whole organization

    Constraints: JSON

  • serviceFilterOptional

    array of string

    Count only usage of these service ids, e.g. ["ec2","rds"]; omitted: every service. An unknown id is accepted and counts nothing

  • alertThresholdsOptional

    array of number

    Percentages of the cap (whole numbers, 1–1000) at which to alert, each once per period; default [80, 100]

    Constraints: integer, 1-1000

  • notificationEmailsOptional

    array of string

    Who is mailed when a threshold fires or an action is proposed; default none (the alert is still recorded and sent as an event). The console’s form fills in your own address

    Constraints: email

  • actionOptional

    object

    Let the budget propose stopping non-production resources: {thresholdPercent (default 100), selector (tag clauses, default environment in dev/development/test/staging/preview)}. A person approves each proposal.

    Constraints: JSON

    May be null.

  • forecastThresholdsOptional

    array of number

    Monthly budgets: also alert (mail and the ews.billing "Budget Threshold Crossed" event, kind forecast) when the month-end forecast reaches these percentages, at most 10 of 1–1000, e.g. [100]. Default none here; the console’s form starts at [100]

    Constraints: integer, 1-1000

    May be null.

Response

201 with the new budget as `list` shows it. 409 QuotaExceeded past the organization’s budget quota (100 standard, 20 trial).

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow billing:CreateBudget on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud billing budgets create --name example --amount-cents 1 --period monthly

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_billing_budgets_create.