Usage Alerts

Usage alerts let you define thresholds on usage metrics, costs, or wallet balances and receive notifications when those thresholds are crossed. They help you stay informed about customer activity without polling the API.

Alert Types

Monigo supports three alert types, each monitoring a different dimension of customer activity.

Usage Exceeded

Fires when a customer’s metered usage on a specific metric crosses a threshold. Useful for notifying customers approaching their plan limits.

curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "usage_exceeded",
    "scope": "plan",
    "scope_id": "PLAN_ID",
    "metric_id": "METRIC_ID",
    "thresholds": [
      { "value": "8000", "label": "80% of limit" },
      { "value": "10000", "label": "100% of limit" }
    ],
    "require_acknowledgment": false
  }'

Cost Exceeded

Fires when the estimated cost for a billing period crosses a threshold. Specify the currency field to match the subscription’s billing currency.

curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cost_exceeded",
    "scope": "subscription",
    "scope_id": "SUBSCRIPTION_ID",
    "currency": "NGN",
    "thresholds": [
      { "value": "50000", "label": "Budget warning" },
      { "value": "100000", "label": "Budget exceeded" }
    ],
    "require_acknowledgment": true
  }'

Wallet Balance Dropped

Fires when a customer’s wallet balance drops below a threshold. Helps you prompt customers to top up before their balance runs out.

curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wallet_balance_dropped",
    "scope": "customer",
    "scope_id": "CUSTOMER_ID",
    "currency": "NGN",
    "thresholds": [
      { "value": "5000", "label": "Low balance" },
      { "value": "1000", "label": "Critical balance" }
    ],
    "require_acknowledgment": false
  }'

Plan-Level Alerts

When you set scope to "plan", the alert applies to every subscription on that plan. Monigo automatically creates per-subscription tracking states when the alert is evaluated, so you do not need to create individual alerts for each customer.

curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "usage_exceeded",
    "scope": "plan",
    "scope_id": "PLAN_ID",
    "metric_id": "METRIC_ID",
    "thresholds": [
      { "value": "800", "label": "80%" },
      { "value": "1000", "label": "100%" }
    ],
    "require_acknowledgment": false
  }'

Multiple Thresholds

Each alert supports multiple thresholds, evaluated in order. When the monitored value crosses the first threshold, Monigo fires a notification and advances to monitoring the next threshold. This lets you set up escalating warnings (for example, 80% and 100%) in a single alert definition. Each threshold has a value (the numeric boundary) and an optional label (a human-readable description included in webhook payloads).

Alert Lifecycle

An alert progresses through these states:

Created — The alert is defined with its thresholds and begins monitoring.
Triggered — The monitored value crosses a threshold. Monigo fires a webhook event and records the triggered state.
Acknowledged — If require_acknowledgment is true, a team member or API call acknowledges the alert. This is recorded for audit purposes.
Reset — At the start of each new billing period, triggered states are automatically reset so thresholds can fire again.

Webhook Events

When thresholds are crossed or alerts change state, Monigo dispatches webhook events to your configured endpoints.

Event Type	Fired When
`alert.triggered`	A threshold is crossed for the first time in the current billing period.
`alert.acknowledged`	A triggered alert is acknowledged via the API or dashboard.
`alert.resolved`	The monitored value drops back below the threshold.
`alert.disabled`	An alert is disabled via the API or dashboard.

Managing Alerts

List Alerts

curl https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by type, scope, or customer:

curl "https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID&type=usage_exceeded&scope=plan" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Thresholds

curl -X PUT https://api.monigo.co/api/v1/alerts/ALERT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "thresholds": [
      { "value": "9000", "label": "90%" },
      { "value": "10000", "label": "100%" }
    ]
  }'

Enable or Disable

# Disable
curl -X POST https://api.monigo.co/api/v1/alerts/ALERT_ID/disable \
  -H "Authorization: Bearer YOUR_API_KEY"

# Enable
curl -X POST https://api.monigo.co/api/v1/alerts/ALERT_ID/enable \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete

curl -X DELETE https://api.monigo.co/api/v1/alerts/ALERT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Use 80%/100% thresholds. An early warning at 80% gives customers time to adjust before hitting the limit.
Enable require_acknowledgment for critical alerts. This ensures someone on your team explicitly reviews cost or usage spikes before they are dismissed.
Combine with webhook endpoints. Route alert.triggered events to Slack, PagerDuty, or your internal tooling for real-time visibility.
Prefer plan-level alerts over per-subscription alerts. Plan-level alerts automatically cover all subscribers and reduce configuration overhead.
Set wallet balance alerts above zero. Alerting at a low-but-nonzero balance gives customers a window to top up before service is interrupted.

Get Started

Concepts

Guides

SDKs

Integrations

API Reference

Alert Types

Usage Exceeded

Cost Exceeded

Wallet Balance Dropped

Plan-Level Alerts

Multiple Thresholds

Alert Lifecycle

Webhook Events

Managing Alerts

List Alerts

Update Thresholds

Enable or Disable

Delete

Best Practices

​Alert Types

​Usage Exceeded

​Cost Exceeded

​Wallet Balance Dropped

​Plan-Level Alerts

​Multiple Thresholds

​Alert Lifecycle

​Webhook Events

​Managing Alerts

​List Alerts

​Update Thresholds

​Enable or Disable

​Delete

​Best Practices

Alert Types

Usage Exceeded

Cost Exceeded

Wallet Balance Dropped

Plan-Level Alerts

Multiple Thresholds

Alert Lifecycle

Webhook Events

Managing Alerts

List Alerts

Update Thresholds

Enable or Disable

Delete

Best Practices