Skip to content

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.

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.

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.

  • 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.v1 event, signed with the endpoint’s secret in the ZB-Signature header 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 to billing.spend_alert.v1 or billing.* 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.

shell
# 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 alerts
zb 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 once
zb 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:

FieldMeaning
alert_idspa_..., unique per alert
team_id, team_nameSet for a team alert
periodMonth, YYYY-MM (UTC)
basisactual or projected
threshold_kindpercent or absolute
threshold_percent, budget_centsFor percentages: the percentage and the cap or team budget
threshold_centsThe threshold as an amount
spend_cents, projected_centsMonth-to-date and projected spend
currencyusd