Merge API Documentation

budget_config is replaced as a whole on PATCH, not merged field by field. Send every field you want to keep: a request carrying only amount resets notification_emails to []. Unknown fields are rejected with a 422.

A project’s budget_config caps its spend over a rolling period. hard_limit rejects the project’s requests with 402 once the limit is reached; soft_limit only fires alerts. Set it on create or PATCH; set it to null to remove the limit.

Fields

Field	Description	Type
`amount`	Budget amount in USD, greater than 0	number
`period`	`daily`, `weekly`, `monthly`, `quarterly`, or `yearly`	enum
`enforcement_mode`	`hard_limit` (requests rejected with `402` at the limit) or `soft_limit` (alerts only)	enum
`alert_thresholds`	Percentages that trigger alerts, e.g. `[80, 90]`	list of integers, 1-100
`notification_emails`	Addresses emailed when a threshold is reached. Recipients do not need a Merge account. Defaults to `[]`, max 20	list of emails
`notify_org_admins`	Whether every organization admin is emailed alongside `notification_emails`. Defaults to `true`: naming recipients adds to the audience rather than replacing it. Set it to `false` to email only the named recipients. While `notification_emails` is empty, one admin is notified so an alert always reaches someone	boolean

Set a budget

$ curl -X PATCH https://api-gateway.merge.dev/v1/projects/{project_id} \
>   -H "Authorization: Bearer mgmt_<your_management_key>" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "budget_config": {
>       "amount": 100,
>       "period": "monthly",
>       "enforcement_mode": "hard_limit",
>       "alert_thresholds": [80, 90],
>       "notification_emails": ["[email protected]"],
>       "notify_org_admins": true
>     }
>   }'

Alerts are evaluated during a request, not on a timer, so a threshold crossing is noticed on the next call for that project. Each threshold emails once per period.

Requests over a hard limit fail with 402 and a project_budget_exceeded error before any provider call, and responses include X-Project-Budget-Remaining-USD and X-Project-Budget-Limit-USD headers as the limit approaches.

Budget changes can take up to an hour to take effect in enforcement. A raised limit doesn’t unblock requests instantly, and a new hard limit doesn’t protect you instantly.