Skip to navigation
Embedded Routing

Budgets

Cap a customer's spend, hard or soft

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
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 yourself.

Reference

FieldTypeDescription
idUUIDBudget ID for GET, PATCH, and DELETE
spending_limitnumberLimit in USD, greater than 0
reset_periodenumDAILY, WEEKLY, MONTHLY, QUARTERLY, or YEARLY
spending_limit_typeenumHARD blocks requests past the limit, SOFT doesn’t
created_at, modified_atdatetimeTimestamps

A customer API key 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

Read spend for one customer or all of them

Customer API keys

Add per-key spend limits