Set or lower a monthly budget
Creates the monthly budget for SMS, OTP or EMAIL, in the wallet currency's minor unit, or tightens the one it has.
https://app.usenotix.dev/api/v1/billing/spend/budgets/{channel}Needs a full access key. Sending access keys cannot call this. Key permissions lists the extra rules some calls have.
Creates the monthly budget for SMS, OTP or EMAIL, in the wallet currency's minor unit, or tightens the one it has. With stopAtLimit true (the default), a text or code that would take the month past its budget is refused with 429 LIMIT_EXCEEDED, and pay-as-you-go email stops at the plan's units once the month's pay-as-you-go charges reach it; false, sending carries on and the team's alerts say so. A budget never moves money and never stops a payment. Budgets reset on the 1st.
The API can only tighten
A key can create a budget, lower its amount, or turn stopAtLimit on. Raising a budget or turning stopAtLimit off answers 403 FORBIDDEN ("Raising or removing a budget can only be done in the dashboard."), so a leaked key cannot lift the limits it is held to. A one-time codes (OTP) budget set here only alerts: one that stops codes is set in the dashboard, because it could stop your users signing in. A stopping EMAIL budget for a team that pays by card answers 400: it would not apply, since only wallet-paid pay-as-you-go can be stopped. Every change is in the team's audit trail with the key's id, and every change made through the API is emailed to the team's admins.
Who can call it
A full access key made by someone who is a team admin today (the team owner always is). Read only, send-only and live AI keys answer 403 SCOPE_DENIED; a key limited to one domain answers 403 DOMAIN_PINNED; a member's key answers 403 FORBIDDEN. The team can change budgets 20 times a minute.
Path parameters
SMS (texts), OTP (one-time codes by text) or EMAIL (pay-as-you-go email).
One of SMS, OTP, EMAIL.
Body parameters
The monthly budget in the wallet currency's minor unit (kobo, cents): 15000000 is ₦150,000. At least one major unit.
Minimum 100. Maximum 2000000000.
True: sending on this channel stops when the month's spend would pass the budget. False: sending carries on and the team's alerts say so. Defaults to true, except for OTP, where it defaults to false: a budget that stops one-time codes can only be set in the dashboard. Turning it off on an existing budget is refused with 403.
Headers
Bearer followed by your API key.
Errors
The amount is not a whole number of minor units, is under one major unit or is too large, the channel is not SMS, OTP or EMAIL, or a stopping EMAIL budget for a team that pays by card (it would not apply).
`SCOPE_DENIED`: a send-only, read-only (on a change) or live AI key. `DOMAIN_PINNED`: a key limited to one domain. `FORBIDDEN`: the key was made by a member who is not a team admin, or before Notix recorded who made each key. `FORBIDDEN` also answers a change the API may not make: raising a budget, removing one, turning `stopAtLimit` off, or a one-time codes (OTP) budget that stops sending. Those are done in the dashboard.
The team changed budgets 20 times in the last minute.
The rate counters cannot be read just now; try again shortly.
Every error has the same shape. See all error codes.
curl -X PUT "https://app.usenotix.dev/api/v1/billing/spend/budgets/<channel>" \
-H "Authorization: Bearer $NOTIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amountMinor": 15000000
}'
{
"channel": "SMS",
"amountMinor": 1,
"amountFormatted": "₦150,000",
"stopAtLimit": true
}