> 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

> The four budget scopes compared: where each is configured, periods, error codes, headers, enforcement timing, and project budget alerts.

Gateway checks four independent budget scopes. The first one exhausted returns `402` before any vendor call, so a blocked request costs nothing.

## The four scopes

| Scope                   | Configured in                                                                                                                            | Periods                                             | On breach (`402` `code`)                                    | Response headers                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Organization credit** | [Billing settings](https://gateway.merge.dev/settings/billing)                                                                           | Balance-based                                       | `budget_exceeded`, or `payment_failed` when a payment fails | `X-Credit-Balance-USD`, `X-Budget-Limit-USD`, `X-Budget-Warning`                           |
| **Project budget**      | The project's **Configuration** tab, or the [Projects API](/merge-gateway/automation/projects-api/budgets)                               | Daily, weekly, monthly, quarterly, yearly           | `project_budget_exceeded`                                   | `X-Project-Budget-Remaining-USD`, `X-Project-Budget-Limit-USD`, `X-Project-Budget-Warning` |
| **Per-key spend limit** | **Spend limit (optional)** when creating a key, or `limit` and `limit_reset` in the [Management API](/merge-gateway/automation/api-keys) | Daily, weekly, monthly                              | `api_key_limit_exceeded`                                    | `X-Key-Limit-Remaining-USD`, `X-Key-Limit-USD`, `X-Key-Limit-Warning`                      |
| **Customer budget**     | The [Embedded Routing customer budget](/merge-gateway/embedded-routing-stack/budgets), one per customer                                  | `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `YEARLY` | `null` (error `type` is `budget_exceeded`)                  | None. Read spend from the customer usage API                                               |

Remaining and limit headers appear while a budget exists; `*-Warning` appears past a warning level (project alert thresholds, or 80 and 90 for per-key limits) and carries that percentage. Enterprise organizations get only `X-Credit-Balance-USD`, which goes negative between invoices. Customer-scoped keys get no organization or project headers.

## How limits are enforced

* **Periods are calendar-aligned in UTC**, not rolling: weekly from Monday, monthly from the 1st, quarterly from January, April, July, and October 1, yearly from January 1
* **Spend is recorded after each request**, so the request that crosses a limit completes and blocking starts with the next
* **Project budgets apply only to requests [scoped](/merge-gateway/cost/projects#scoping-requests-to-a-project) by a project API key or the `X-Project-Id` header**, never to one naming its project only in the `project_id` body field

> **Warning**
>
> Budget changes take up to an hour to enforce, whether raising a limit or adding a hard one.

## Soft vs hard limits

A **soft limit** alerts and never blocks. A **hard limit** alerts, then returns `402` until the period resets or you raise it. The Projects API spells them `soft_limit` and `hard_limit`; the Embedded Routing API, `SOFT` and `HARD`.

## Project budget alerts

Thresholds are budget percentages: the dashboard pre-fills 50%, 80%, and 90%, and an API-created budget has none unless sent. An alert sends on the project's first request after a crossing.

Alerts go to the budget's recipients (any address, no Merge account needed) plus every admin while **Also notify organization admins** is on (the default). With it off and no recipients, one admin is emailed.

Each threshold emails when first crossed, with at most one reminder seven days later; a higher threshold emails right away, and a hard limit emails when it starts blocking. The throttle resets each calendar month regardless of budget period.

## Choosing a scope

Give every production workload a project budget, the scope with alert emails, and add per-key limits to keys you hand out so one credential can't drain a project. Organization credit is the backstop; customer budgets apply only if you resell Gateway through the [Embedded Routing Stack](/merge-gateway/embedded-routing-stack/overview).

## Next steps

#### [Projects](/merge-gateway/cost/projects)

Create a project and scope requests so its budget applies

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

Manage project budgets from infrastructure-as-code

#### [Cost governance and savings](/merge-gateway/cost/cost-governance-and-savings)

See where spend is reported and the settings that cut it