Usage Alerts & Thresholds

Overview

BoxBilling provides two mechanisms for monitoring usage: usage alerts track consumption against billable metrics, while usage thresholds track spending against monetary amounts. Both can trigger notifications and, in the case of thresholds, automatic mid-cycle invoicing.

Usage alerts vs usage thresholds

	Usage alerts	Usage thresholds
Tracks	Billable metric consumption	Monetary spend (amount in cents)
Scope	Per subscription + metric	Per plan or subscription
Trigger	Usage reaches threshold value	Spend reaches amount in cents
Recurring	Optional — can re-trigger each period	Optional — can re-trigger each period
Use case	”Alert when API calls hit 10,000"	"Invoice when spend reaches $500”

Usage alerts

How usage alerts work

Create alert ──► subscription + metric + threshold
        │
        ▼
Usage accumulates during billing period
        │
        ▼
Usage reaches threshold_value
        │
        ▼
Alert triggers ──► webhook notification
        │
        ▼
(If recurring) ──► resets for next period

Alert properties

Field	Type	Description
id	uuid	Unique alert identifier
organization_id	uuid	Organization that owns the alert
subscription_id	uuid	Subscription being monitored
billable_metric_id	uuid	Metric being tracked
threshold_value	decimal	Value that triggers the alert
recurring	boolean	Whether the alert resets each billing period (default: false)
name	string?	Optional display name (max 255 chars)
times_triggered	integer	Total number of times the alert has fired
triggered_at	datetime?	When the alert last triggered
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Create a usage alert

curl -X POST /v1/usage_alerts/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "subscription-uuid",
    "billable_metric_id": "metric-uuid",
    "threshold_value": 10000,
    "recurring": true,
    "name": "API calls warning"
  }'

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "org-uuid",
  "subscription_id": "subscription-uuid",
  "billable_metric_id": "metric-uuid",
  "threshold_value": "10000",
  "recurring": true,
  "name": "API calls warning",
  "times_triggered": 0,
  "triggered_at": null,
  "created_at": "2026-03-08T10:00:00Z",
  "updated_at": "2026-03-08T10:00:00Z"
}

Set recurring to true for alerts that should fire every billing period when the threshold is reached. Non-recurring alerts fire once and then remain inactive.

Update a usage alert

curl -X PATCH /v1/usage_alerts/{alert_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold_value": 15000,
    "name": "API calls warning (updated)"
  }'

You can update threshold_value, name, and recurring. Changes take effect immediately.

Get a usage alert

curl /v1/usage_alerts/{alert_id} \
  -H "Authorization: Bearer $API_KEY"

Delete a usage alert

curl -X DELETE /v1/usage_alerts/{alert_id} \
  -H "Authorization: Bearer $API_KEY"

Returns 204 No Content on success.

List usage alerts

curl /v1/usage_alerts/ \
  -H "Authorization: Bearer $API_KEY"

Supports pagination with skip and limit query parameters. Filter by subscription using subscription_id query parameter.

Check alert status

Get the current usage level relative to the alert threshold.

curl /v1/usage_alerts/{alert_id}/status \
  -H "Authorization: Bearer $API_KEY"

Response (200):

{
  "alert_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_usage": "7500",
  "threshold_value": "10000",
  "usage_percentage": "75.0",
  "billing_period_start": "2026-03-01T00:00:00Z",
  "billing_period_end": "2026-03-31T23:59:59Z"
}

The usage_percentage shows how close the subscription is to triggering the alert. Use this to build dashboards or proactive notifications.

View trigger history

curl /v1/usage_alerts/{alert_id}/triggers \
  -H "Authorization: Bearer $API_KEY"

Response (200):

[
  {
    "id": "trigger-uuid",
    "usage_alert_id": "550e8400-e29b-41d4-a716-446655440000",
    "current_usage": "10250",
    "threshold_value": "10000",
    "metric_code": "api_calls",
    "triggered_at": "2026-03-15T14:30:00Z"
  }
]

Each trigger records the usage level and metric code at the moment the alert fired.

Test an alert

Check whether an alert would trigger based on current usage without actually firing it.

curl -X POST /v1/usage_alerts/{alert_id}/test \
  -H "Authorization: Bearer $API_KEY"

Use this during setup to verify alert configuration before going live.

Usage thresholds

Usage thresholds monitor monetary spend and can trigger automatic mid-cycle invoicing when a spending limit is reached.

Threshold properties

Field	Type	Description
id	uuid	Unique threshold identifier
plan_id	uuid?	Plan this threshold belongs to (if plan-level)
subscription_id	uuid?	Subscription this threshold belongs to (if subscription-level)
amount_cents	decimal	Spending amount that triggers the threshold
currency	string	Three-letter currency code (default: USD)
recurring	boolean	Whether the threshold resets each billing period (default: false)
threshold_display_name	string?	Custom label (max 255 chars)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Create a plan-level threshold

Thresholds created on a plan apply to all subscriptions using that plan.

curl -X POST /v1/plans/pro_monthly/usage_thresholds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 50000,
    "currency": "USD",
    "recurring": true,
    "threshold_display_name": "Mid-cycle invoice at $500"
  }'

Response (201):

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "plan_id": "plan-uuid",
  "subscription_id": null,
  "amount_cents": "50000",
  "currency": "USD",
  "recurring": true,
  "threshold_display_name": "Mid-cycle invoice at $500",
  "created_at": "2026-03-08T10:00:00Z",
  "updated_at": "2026-03-08T10:00:00Z"
}

Create a subscription-level threshold

For more granular control, create thresholds on individual subscriptions.

curl -X POST /v1/subscriptions/{subscription_id}/usage_thresholds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 100000,
    "currency": "USD",
    "recurring": false
  }'

List thresholds

# Plan-level thresholds
curl /v1/plans/pro_monthly/usage_thresholds \
  -H "Authorization: Bearer $API_KEY"

# Subscription-level thresholds
curl /v1/subscriptions/{subscription_id}/usage_thresholds \
  -H "Authorization: Bearer $API_KEY"

Delete a threshold

curl -X DELETE /v1/usage_thresholds/{threshold_id} \
  -H "Authorization: Bearer $API_KEY"

Returns 204 No Content on success.

Entity relationships

• Subscriptions — usage alerts monitor a subscription’s metric consumption; thresholds can be set per subscription
• Plans — usage thresholds can be defined at the plan level, applying to all subscriptions
• Billable metrics — usage alerts track a specific metric’s accumulation
• Invoices — usage thresholds can trigger mid-cycle invoice generation when spending limits are reached

API endpoints

Usage alerts

Method	Path	Description
POST	/v1/usage_alerts/	Create a usage alert
GET	/v1/usage_alerts/	List usage alerts
GET	/v1/usage_alerts/{alert_id}	Get a usage alert
PATCH	/v1/usage_alerts/{alert_id}	Update a usage alert
DELETE	/v1/usage_alerts/{alert_id}	Delete a usage alert
GET	/v1/usage_alerts/{alert_id}/status	Get alert status with current usage
GET	/v1/usage_alerts/{alert_id}/triggers	List alert trigger history
POST	/v1/usage_alerts/{alert_id}/test	Test alert against current usage

Usage thresholds

Method	Path	Description
POST	/v1/plans/{plan_code}/usage_thresholds	Create a plan-level threshold
GET	/v1/plans/{plan_code}/usage_thresholds	List plan thresholds
POST	/v1/subscriptions/{subscription_id}/usage_thresholds	Create a subscription-level threshold
GET	/v1/subscriptions/{subscription_id}/usage_thresholds	List subscription thresholds
DELETE	/v1/usage_thresholds/{threshold_id}	Delete a threshold