Help
Spend alerts
Tested with:Databasezy API v1 · zb CLI 0.1
Spend alerts tell you when spending this month crosses an amount you care about. They never stop, pause or slow anything: they are a heads-up. Only your monthly spending cap refuses new databases and resizes.
What you can set
Section titled “What you can set”Under Billing → Spend alerts, someone with billing:manage (owners, admins and billing members) sets:
- Percentages of the cap: for example 50, 80 and 100. The warning percentage you set with the monthly spending cap always applies too, so an organization with a cap gets an alert at that percentage without any other setup. Percentages need a cap; without one only amounts apply.
- Amounts in US dollars: for example 250 and 1000, whether or not you have a cap.
- Projected alerts (optional): also alert when the projected end-of-month spend crosses a threshold before the actual spend does.
- Team alerts: the same settings for one team, with percentages of the team’s budget (set on the team). Team spend is the usage of the team’s databases.
Limits: percentages 1 to 200, amounts $0.01 to $1,000,000,000, at most 10 of each per organization or team, and at most 100 teams.
How spend is measured
Section titled “How spend is measured”Spend is this calendar month’s usage (UTC) at list price, before plan allowances and credits. It is the same figure the monthly spending cap is checked against, so “80% of your cap” means the same thing in both places. Your invoice can be lower because allowances and credits are applied when it is built.
The projection is the spend so far plus the average hourly spend of the last 24 rated hours for the rest of the month. It starts on the second day of the month.
Usage is rated hourly, after each hour closes. Alerts are checked within a minute of new usage being rated and at least every 15 minutes, so an alert arrives within about an hour and a quarter of spend crossing a threshold.
Who gets the alert
Section titled “Who gets the alert”- Email to the organization’s owners, admins and billing members whose email address is verified, as they are when the alert fires. Turning off billing emails in your notification preferences turns these off too.
- Webhooks (optional): add an endpoint under Billing → Spend alert webhooks (owners and admins). Each alert
is posted as the
billing.spend_alert.v1event, signed with the endpoint’s secret in theZB-Signatureheader like every Databasezy webhook. HTTPS only; private, loopback and internal addresses are refused when you add the endpoint and again on every delivery. Any org webhook subscribed tobilling.spend_alert.v1orbilling.*receives alerts. - Alerts in the portal list them too.
Each threshold alerts once a month for each of actual and projected spend. When spend jumps past several thresholds at once you get one alert, for the highest. Raising the cap re-arms its percentages for the new amount.
# settings, this month's spend and projection, and this month's alerts (billing:read)zb api GET /v1/orgs/{org}/spend-alerts
# replace the settings (billing:manage); teams left out lose their alertszb api PUT /v1/orgs/{org}/spend-alerts --data '{ "org": {"percent_thresholds": [50, 100], "absolute_thresholds_cents": [25000], "projected": true}, "teams": [{"team_id": "team_...", "percent_thresholds": [90]}]}'
# receive alerts by webhook (org:manage); the secret is returned oncezb api POST /v1/orgs/{org}/webhooks --data '{"url": "https://hooks.example.com/zb", "events": ["billing.spend_alert.v1"]}'The cap and team budgets come from your organization’s settings, never from the request. A team id that is not a
team of your organization is refused with 422. Every change is in the audit log as org.spend_alerts.update.
The billing.spend_alert.v1 payload:
| Field | Meaning |
|---|---|
alert_id | spa_..., unique per alert |
team_id, team_name | Set for a team alert |
period | Month, YYYY-MM (UTC) |
basis | actual or projected |
threshold_kind | percent or absolute |
threshold_percent, budget_cents | For percentages: the percentage and the cap or team budget |
threshold_cents | The threshold as an amount |
spend_cents, projected_cents | Month-to-date and projected spend |
currency | usd |