​

Spend caps, budget alerts, and auto-cutoff

​

1. Alert rules — your org’s thresholds

• GET /api/v1/billing/alerts / GET /api/v1/billing/alerts/:id — list and read rules.
• POST /api/v1/billing/alerts — create one.
• POST /api/v1/billing/alerts/:id/test — dry-run a rule against today’s metrics without stamping it or pausing anything.

curl -X POST https://api.orbit.devotel.io/api/v1/billing/alerts \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "80% of monthly budget — page me, then pause",
    "threshold_type": "spend_percent",
    "threshold_value": 80,
    "currency": "USD",
    "notify_emails": ["ops@example.com"],
    "notify_sms_numbers": ["+15551234567"],
    "action_on_hit": "pause_outbound",
    "cooldown_hours": 24
  }'

​

2. What happens when a rule trips

1. Notifications go out. Every email and SMS recipient receives one message per firing, with the rule’s name, the threshold descriptor, and the observed value (e.g. “Observed 82.4% against a threshold of 80% of monthly budget”).
2. last_triggered_at is stamped. Until the cooldown expires the same rule stays quiet — the 10-minute tick never turns into a notification storm while spend hovers just above the line.
3. The action fires (if you chose one). pause_outbound sets outbound_paused = TRUE in a single UPDATE and immediately invalidates the cached outbound-flags entry across every API pod, so the send pipeline re-reads the flag on the next send call — not up to five minutes later. block_outbound does the same against the stricter outbound_blocked flag.

​

3. Self-serve daily agent spend cap

• GET /api/v1/settings/agents/spend-cap — read the cap, today’s spend so far, and the server-computed cap_reached flag in one payload.
• PUT /api/v1/settings/agents/spend-cap — set or clear it. null removes the cap entirely.

curl -X PUT https://api.orbit.devotel.io/api/v1/settings/agents/spend-cap \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "daily_spend_cap_cents": 50000 }'

​

4. Sub-account kill-switch — reseller budgets as a hard latch

​

5. Cooldowns — how repeat trips debounce

• cooldown_hours on an org rule anchors a repeat-notification silence. Stamp + cooldown window = a jittery threshold emits at most one email/SMS per window, not once per 10-minute tick.
• The per-sub-account kill-switch re-arms per UTC billing month automatically — a latch written last month is invisible to this month’s gate.
• The agent daily cap re-arms at UTC midnight. Raising the cap via PUT /settings/agents/spend-cap re-arms the gate immediately rather than waiting for the next UTC boundary.

​

6. Dashboard ↔ API parity

• Billing → Alerts — create/read/test-fire the four threshold types, configure email/SMS recipients, pick the action, pick the cooldown. The monthly-budget cap lives ON THIS PAGE in a dedicated card — the percent-of-budget denominator — with an inline editor, so you can set or clear the cap without leaving Billing. (The same value is also editable under Settings → Account → General, where the full org settings form lives; both surfaces write the same value.)
• Billing → Balance — the header widget and the balance-read endpoint both display the org’s current outbound-paused flag so operators see a cut-off org before they see the pause error on a send.
• Settings → Agents — the agent-spend-cap card on the settings surface, plus an auto-pause banner on the agents list when cap_reached is true.