> 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

> Set a per-customer spend limit that blocks requests once exhausted, or a soft limit that keeps serving.

A budget limits a customer's spend over a reset period. `HARD` stops serving the customer at the limit; `SOFT` sets a figure you track without blocking traffic.

## Set a budget

A customer has at most one budget, and a second `POST` returns `409`.

**`cURL`**

```bash title="cURL"
curl -X POST https://api-gateway.merge.dev/v1/customers/{customer_id}/budgets \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "spending_limit": 50, "reset_period": "MONTHLY", "spending_limit_type": "HARD" }'
```

An exhausted `HARD` budget returns `402` `budget_exceeded` until the period resets. To resume sooner, raise `spending_limit` or switch to `SOFT` with `PATCH /v1/customers/{customer_id}/budgets/{budget_id}` (only the fields you send change). `DELETE` on the same path removes the budget.

A `SOFT` budget sends no notification, so compare it against [usage](/merge-gateway/embedded-routing-stack/usage) yourself.

## Reference

| Field                       | Type     | Description                                            |
| --------------------------- | -------- | ------------------------------------------------------ |
| `id`                        | UUID     | Budget ID for `GET`, `PATCH`, and `DELETE`             |
| `spending_limit`            | number   | Limit in USD, greater than 0                           |
| `reset_period`              | enum     | `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, or `YEARLY` |
| `spending_limit_type`       | enum     | `HARD` blocks requests past the limit, `SOFT` doesn't  |
| `created_at`, `modified_at` | datetime | Timestamps                                             |

A [customer API key](/merge-gateway/embedded-routing-stack/customer-api-keys) can read its budget but not create, change, or delete it. For a per-key cap on top of the budget, set the key's `spending_limit`.

## Next steps

#### [Usage](/merge-gateway/embedded-routing-stack/usage)

Read spend for one customer or all of them

#### [Customer API keys](/merge-gateway/embedded-routing-stack/customer-api-keys)

Add per-key spend limits