> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Budgets

> Configure budget_config on a project: amount, period, hard or soft enforcement, alert thresholds, and recipients, and how PATCH replaces the whole object.

`budget_config` caps a project's spend per period and emails recipients as spend crosses thresholds. Set it on create or `PATCH`; `null` removes the budget. Enforcement, alert timing, and blocked-request errors and headers are in [Budgets](/merge-gateway/cost/budgets).

## Reference

| Field                 | Required | Meaning                                                                                                        |
| --------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `amount`              | Yes      | Limit in USD, greater than 0                                                                                   |
| `period`              | Yes      | `daily`, `weekly`, `monthly`, `quarterly`, or `yearly`, calendar-aligned in UTC                                |
| `enforcement_mode`    | Yes      | `hard_limit` returns `402 project_budget_exceeded` at the limit. `soft_limit` only alerts                      |
| `alert_thresholds`    | No       | Percentages from 1 to 100, such as `[50, 80, 90]`. Defaults to `[]`, which sends no threshold alerts           |
| `notification_emails` | No       | Up to 20 recipients, with or without a Merge account. Defaults to `[]`                                         |
| `notify_org_admins`   | No       | Also emails every organization admin. Defaults to `true`. With `false` and no recipients, one admin is emailed |

> **PATCH replaces the whole budget**
>
> `budget_config` isn't merged: an omitted optional field reverts to its default, so a `PATCH` without `alert_thresholds` turns threshold alerts off. Send every field you want to keep.

## Set a budget

```bash
curl -X PATCH https://api-gateway.merge.dev/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $MERGE_GATEWAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "budget_config": {
      "amount": 100,
      "period": "monthly",
      "enforcement_mode": "hard_limit",
      "alert_thresholds": [50, 80, 90],
      "notification_emails": ["finance@acme.com"],
      "notify_org_admins": true
    }
  }'
```

Changes take up to an hour to reach enforcement. See [which requests the hard limit blocks](/merge-gateway/cost/budgets#how-limits-are-enforced).

## Next steps

#### [Budgets](/merge-gateway/cost/budgets)

See how enforcement, alerts, and the other scopes work

#### [Usage](/merge-gateway/automation/projects-api/usage)

Read a project's spend

#### [Projects API](/merge-gateway/automation/projects-api)

Manage the rest of a project's configuration