Skip to content
Metronome Docs
  • Auto
  • Light
  • Dark
Talk to an expert

Create

API Reference
V1
Alerts
Create an alert
client.v1.alerts.create(AlertCreateParamsbody, RequestOptionsoptions?): dataIDAlertCreateResponse
post/v1/alerts/create

Create a new alert

Parameters
bodyalert_typeunionnamestringthresholdnumberbillable_metric_idstringcredit_grant_type_filtersarraycredit_type_idstringcustom_field_filtersarraycustomer_idstringevaluate_on_createbooleangroup_valuesarrayinvoice_types_filterarrayplan_idstringuniqueness_keystringAlertCreateParams
Hide ParametersShow Parameters
alert_typeunion
"low_credit_balance_reached" | "spend_threshold_reached" | "monthly_invoice_total_spend_threshold_reached" | 11 more

Type of the alert

Hide ParametersShow Parameters
"low_credit_balance_reached"
"spend_threshold_reached"
"monthly_invoice_total_spend_threshold_reached"
"low_remaining_days_in_plan_reached"
"low_remaining_credit_percentage_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"
namestring

Name of the alert

thresholdnumber

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

billable_metric_idstring
optional

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

formatuuid
credit_grant_type_filtersarray
optional
Array<string>

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

credit_type_idstring
optional

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

formatuuid
custom_field_filtersarray
optional
Array<CustomFieldFilter>

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

Hide ParametersShow Parameters
entityunion
"Contract" | "Commit" | "ContractCredit"
Hide ParametersShow Parameters
"Contract"
"Commit"
"ContractCredit"
keystring
valuestring
customer_idstring
optional

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

formatuuid
evaluate_on_createboolean
optional

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

group_valuesarray
optional
Array<GroupValue>

Only present for spend_threshold_reached alerts. Scope alert to a specific group key on individual line items.

Hide ParametersShow Parameters
keystring
valuestring
invoice_types_filterarray
optional
Array<string>

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

plan_idstring
optional

If provided, will create this alert for this specific plan. To create an alert for all customers, do not specify a plan_id.

formatuuid
uniqueness_keystring
optional

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.

minLength1
maxLength128
Returns
AlertCreateResponse
Hide ParametersShow Parameters
dataidstringID
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

const alert = await client.v1.alerts.create({
  alert_type: 'spend_threshold_reached',
  name: '$100 spend threshold reached',
  threshold: 10000,
  credit_grant_type_filters: ['enterprise'],
  credit_type_id: '2714e483-4ff1-48e4-9e25-ac732e8f24f2',
  customer_id: '4db51251-61de-4bfe-b9ce-495e244f3491',
});

console.log(alert.data);
200 Example
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  }
}