Merge API Documentation

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.

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

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.

Next steps

Budgets

See how enforcement, alerts, and the other scopes work

Usage

Read a project’s spend

Projects API

Manage the rest of a project’s configuration