Create a threshold notification

curl --request POST \
  --url https://api.metronome.com/v1/alerts/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "alert_type": "spend_threshold_reached",
  "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
  "name": "$100 spend threshold reached",
  "threshold": 10000,
  "customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491",
  "credit_grant_type_filters": [
    "enterprise"
  ]
}
'

{
  "data": {
    "id": "58fb0650-e54a-4d17-93cb-ba8e56c32c65"
  }
}

Notifications

Create a threshold notification

Create a new threshold notification to monitor customer spending, balances, and billing metrics in real-time. Metronome’s notification system provides industry-leading speed with immediate evaluation capabilities, enabling you to proactively manage customer accounts and prevent revenue leakage.

This endpoint creates configurable threshold notifications that continuously monitor various billing thresholds including spend limits, credit balances, commitment utilization, and invoice totals. Threshold notifications can be configured globally for all customers or targeted to specific customer accounts.

Use this endpoint to:

Proactively monitor customer spending patterns to prevent unexpected overages or credit exhaustion
Automate notifications when customers approach commitment limits or credit thresholds
Enable real-time intervention for accounts at risk of churn or payment issues
Scale billing operations by automating threshold-based workflows and notifications

Key response fields:

A successful response returns a CustomerAlert object containing:

The threshold notification configuration with its unique ID and current status
The customer’s evaluation status (ok, in_alarm, or evaluating)
Threshold notification metadata including type, threshold values, and update timestamps

Usage guidelines:

Immediate evaluation: Set evaluate_on_create : true (default) for instant evaluation against existing customers
Uniqueness constraints: Each threshold notification must have a unique uniqueness_key within your organization. Use release_uniqueness_key : true when archiving to reuse keys
Notification type requirements: Different threshold notification types require specific fields (e.g., billable_metric_id for usage notifications, credit_type_id for credit-based threshold notifications)
Webhook delivery: Threshold notifications trigger webhook notifications for real-time integration with your systems. Configure webhook endpoints before creating threshold notifications
Performance at scale: Metronome’s event-driven architecture processes threshold notification evaluations in real-time as usage events stream in, unlike competitors who rely on periodic polling or batch evaluation cycles

POST

alerts

create

Create a threshold notification

curl --request POST \
  --url https://api.metronome.com/v1/alerts/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "alert_type": "spend_threshold_reached",
  "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
  "name": "$100 spend threshold reached",
  "threshold": 10000,
  "customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491",
  "credit_grant_type_filters": [
    "enterprise"
  ]
}
'

{
  "data": {
    "id": "58fb0650-e54a-4d17-93cb-ba8e56c32c65"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The details of the threshold notification to create

alert_type

enum<string>

required

Type of the threshold notification

Available options:

spend_threshold_reached,

monthly_invoice_total_spend_threshold_reached,

usage_threshold_reached,

low_remaining_days_for_commit_segment_reached,

low_remaining_commit_balance_reached,

low_remaining_commit_percentage_reached,

low_remaining_days_for_contract_credit_segment_reached,

low_remaining_contract_credit_balance_reached,

low_remaining_contract_credit_percentage_reached,

low_remaining_contract_credit_and_commit_balance_reached,

invoice_total_reached,

low_remaining_seat_balance_reached

name

string

required

Name of the threshold notification

threshold

number

required

Threshold value of the notification policy. Depending upon the notification type, this number may represent a financial amount, the days remaining, or a percentage reached.

uniqueness_key

string

Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error.

Required string length: 1 - 128

credit_type_id

string<uuid>

ID of the credit's currency, defaults to USD. If the specific notification type requires a pricing unit/currency, find the ID in the Metronome app.

customer_id

string<uuid>

If provided, will create this threshold notification for this specific customer. To create a notification for all customers, do not specify a customer_id.

billable_metric_id

string<uuid>

For threshold notifications of type usage_threshold_reached, specifies which billable metric to track the usage for.

credit_grant_type_filters

string[]

An array of strings, representing a way to filter the credit grant this threshold notification applies to, by looking at the credit_grant_type field on the credit grant. This field is only defined for CreditPercentage and CreditBalance notifications

evaluate_on_create

boolean

If true, the threshold notification will evaluate immediately on customers that already meet the notification threshold. If false, it will only evaluate on future customers that trigger the threshold. Defaults to true.

custom_field_filters

object[]

A list of custom field filters for threshold notification types that support advanced filtering. Only present for contract invoices.

Show child attributes

invoice_types_filter

string[]

Only supported for invoice_total_reached threshold notifications. A list of invoice types to evaluate.

group_values

object[]

Only present for spend_threshold_reached notifications. Scope notification to a specific group key on individual line items.

Show child attributes

seat_filter

object

Required for low_remaining_seat_balance_reached notifications. The alert is scoped to this seat group key-value pair.

Show child attributes

Response

200 - application/json

Success

data

object

required

Show child attributes

Void an invoice

Get a threshold notification

⌘I