# Create a budget

Create a budget for the organization, a project, a saved view or a set of tags, choose when it alerts and who is mailed, and check what it covers before you save it.

A budget alerts; it never stops anything by itself (see [Budgets](budgets.md)). Replace
_Platform team_ with a name of your own, and _jane.doe@example.com_ with the address to mail.

## Prerequisites

- Permission for `billing:CreateBudget`. Without it, the console says "Creating one needs
  billing:CreateBudget, which your policies do not grant."
- In the console, also `billing:GetBudgets` to open **Budgets** (without it the page shows an
  access-denied notice).
- To scope by tags, `tags:ListTags`; by a saved view, `tags:ListProjects`; by a project,
  `projects:ListProjects`. Without them the console offers only **The whole organization**, and
  says which permission the other choices need.
- To check a scope before saving, `billing:GetBudgets` and `tags:ListTags`.
- Room in the **Budgets** quota (see [Quotas](quotas.md)).

## Create the budget

Budgets are free.

**Console**
1. Open **Budgets**, then choose **Create budget**.
2. Under **The alert**, for **Name**, enter Platform team.
3. For **Alert me at (EUR)**, enter the amount, for example 500.
4. For **Period**, choose **Monthly**, **Quarterly** or **Annual**.
5. Under **What it covers**, choose **The whole organization**, **A project**, **A saved view** or
   **Resources with a tag**, and pick the project or view, or enter the tag keys and values. Below
   the choice, the form says how many billable resources the scope covers, or warns when it covers
   none.
6. (Optional) Under **Services**, select the services to count. Leave all clear to count every
   service.
7. Under **Who hears about it**, change **Alert thresholds** (the form starts at `80,100`) and,
   for a monthly budget, **Forecast thresholds** (the form starts at `100`).
8. For **Notification emails**, keep your own address, which the form fills in, or enter others.
9. (Optional) Under **Suggest what to stop**, select the check box to let the budget propose
   stopping non-production resources (see
   [Let a budget propose stopping resources](stop-resources-with-a-budget.md)).
10. Choose **Create budget**.

If you close the dialog before creating, what you typed is kept for the next time you open it.

**CLI**
```sh
dcloud billing budgets create --name "Platform team" --amount-cents 50000 \
  --period monthly --scope '{"type":"tags","clauses":[{"key":"team","values":["platform"]}]}' \
  --notification-emails jane.doe@example.com
```

**API**
```http
POST /billing/api/budgets
{
  "name": "Platform team",
  "amountCents": 50000,
  "period": "monthly",
  "scope": { "type": "tags", "clauses": [{ "key": "team", "values": ["platform"] }] },
  "alertThresholds": [50, 80, 100],
  "forecastThresholds": [100],
  "notificationEmails": ["jane.doe@example.com"]
}
```

**Terraform**
```hcl
resource "dcloud_budget" "platform" {
  name                = "Platform team"
  amount_cents        = 50000
  period              = "monthly"
  scope               = jsonencode({ type = "tags", clauses = [{ key = "team", values = ["platform"] }] })
  alert_thresholds    = [80, 100]
  forecast_thresholds = [100]
  notification_emails = ["jane.doe@example.com"]
}
```

The console and the API start from different defaults:

| Field                | Console form               | API, CLI and Terraform                                       |
| -------------------- | -------------------------- | ------------------------------------------------------------ |
| `period`             | Monthly                    | Required                                                     |
| `scope`              | The whole organization     | The whole organization                                       |
| `alertThresholds`    | 80, 100                    | `[80, 100]`                                                  |
| `forecastThresholds` | 100 (monthly budgets only) | None                                                         |
| `notificationEmails` | Your own address           | None: alerts are recorded and sent as events, but not mailed |

## Check a scope before you save it

The console checks the scope as you type it. Over the API:

```http
POST /billing/api/budgets/scope-preview
{ "scope": { "type": "tags", "clauses": [{ "key": "team", "values": ["platform"] }] } }
```

The answer says how many resources the scope selects (`matched`), how many of them are billed now
(`billable`), by type, and `valid: false` with an `error` for a project or saved view that does not
exist. Nothing is written.

## Result

The budget exists and is evaluated every hour. It appears on **Budgets** with what it has used in
the current period.

## When creation is refused

- `409` "Quota exceeded: Budgets (billing.budgets) — …" when the quota is used up.
- `400` when a threshold is not a whole number from 1 to 1000, an address is not an e-mail address,
  or a tag key is not lowercase starting with a letter.

A project or saved view id that does not exist is accepted: the budget is created with a broken
scope and watches nothing. A service id in `serviceFilter` that does not exist is accepted too and
counts nothing.

## Related

- [Budgets](budgets.md)
- [Edit or delete a budget](edit-or-delete-a-budget.md)
- `billing.budgets.create` · `dcloud billing budgets create` · `dcloud_budget`
