​

Spend caps on the dashboard

​

1. Where the cap panel lives — and how it relates to the wallet

• The monthly-budget card — a dedicated card at the top of Billing → Alerts with an inline editor. It stores org monthly_budget_cents, the denominator every spend_percent rule computes against. The same value is editable under Settings → Account → General (both surfaces write one value). Until you set it, spend_percent rules report themselves inapplicable and the dashboard disables the percent option with a “set a monthly budget first” pointer.
• The alert-rules list — the threshold rules themselves: metric, threshold, recipients, action, cooldown. Create, read, and dry-run them here.

​

2. Set a cap: budget first, then a layered rule set

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": "70% of monthly budget — notify ops",
    "threshold_type": "spend_percent",
    "threshold_value": 70,
    "currency": "USD",
    "notify_emails": ["ops@example.com"],
    "action_on_hit": "notify",
    "cooldown_hours": 12
  }'

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": "90% of monthly budget — pause outbound",
    "threshold_type": "spend_percent",
    "threshold_value": 90,
    "currency": "USD",
    "notify_emails": ["ops@example.com"],
    "notify_sms_numbers": ["+15551234567"],
    "action_on_hit": "pause_outbound",
    "cooldown_hours": 12
  }'

• notify — soft. Recipients get email/SMS; traffic untouched. Use for warning bands.
• pause_outbound — hard. Sets the org’s outbound-paused flag; new sends return 402 SENDING_PAUSED until a human clears the alert in the dashboard.
• block_outbound — hard, operator-reviewed. The stricter gate used when the stop should hold until someone looks at it, not just until someone clicks clear.

​

3. Rehearse the over-cap path in sandbox

1. Calc the probe size. Set the sandbox budget to a small value (e.g. $5). One message to a magic-number recipient resolves delivered per the sandbox magic-numbers table (for pause drills you do not need a failure scenario — you need a countable, cheap send). The what-if preview endpoint from api-recipes task 22 prices a send before you fire it.
2. Arm a low threshold. Create a spend_amount rule with a threshold of one message’s cost (or a daily_spend rule with a handful of cents) and action_on_hit: "pause_outbound". Low thresholds in sandbox are free; in production this same shape is how you test without touching live traffic.
3. Send until the tick trips. Fire one sandbox send per the numbered example below; wait for the billing scheduler’s 10-minute tick to evaluate; watch the recipients receive the rule’s name plus the observed value, then confirm the paused flag.

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15005550002",
    "from": "+15005550101",
    "body": "cap drill"
  }'

4. Read the state. GET /api/v1/billing/alerts shows the rule’s last_triggered_at stamped; the dashboard wallet header shows the org paused.

​

4. What happens on over-cap

​

5. Recover: raise the cap, top up, or split traffic

1. Raise the cap. When the rule was too tight for legitimate volume, edit the rule’s threshold_value in Billing → Alerts, then clear the tripped gate with POST /api/v1/billing/alerts/reset-outbound (owner or admin; the dashboard’s clear button calls the same route). The gate re-arms once you have cleared, with the new threshold in effect from the next tick.
2. Top up. When a balance_remaining floor or INSUFFICIENT_BALANCE was the stop, auto top-up keeps the wallet funded at a chosen trigger level so the floor rule trips less; manual top-up ends the current stoppage immediately.
3. Split traffic. When one sender profile keeps smashing the org-wide line, move it to a sub-account with its own monthly latched cap (reseller pattern, Spend caps §4) — the blast radius shrinks to that child account and the rest of the org keeps sending.

​

6. Per-channel and per-scope caps

• Org-wide rules (Billing → Alerts) measure one org-wide metric — there is no per-country org alert; the metric family covers percent/amount/daily/balance, not destination.
• Agent LLM spend has its own daily USD cap under Settings → Agents (GET/PUT /api/v1/settings/agents/spend-cap) — the details are in Spend caps §3, refused with AGENT_DAILY_SPEND_CAP_REACHED (429).
• Sub-accounts (resellers) get a hard per-child monthly latch that stays tripped until a new UTC month or a refund releases it — per destination without per-country selection.
• The fraud envelope’s per-channel daily ceilings exist precisely because org alert rules are global — they take up the per-channel slack your rules cannot express.

​

7. Pair with anomaly rules and recipes

​

8. Next: API-level budgets