Sample - Stripe API
POST/v1/billing/alerts

Create a billing alert

Creates a billing alert that notifies you when a usage threshold on a meter is crossed. Supply alert_type and title, and provide usage_threshold to define the meter, threshold, recurrence, and optional filters.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

4 body fields

Billing alert configuration submitted as form-encoded data.

alert_typestringrequired
The type of alert to create.
Allowed:usage_threshold
expandarray<string>optional
Specifies which fields in the response should be expanded.
titlestringrequired
The title of the alert.
usage_thresholdobjectoptional
The configuration of the usage threshold.

2 status codes
200Returns the created billing alert, including its identifier, alert type, title, mode, status, and usage-threshold configuration.
alert_typestringrequired
Defines the type of the alert.
Allowed:usage_threshold
idstringrequired
Unique identifier for the object.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:billing.alert
statusstringoptional
Status of the alert. This can be active, inactive or archived.
Allowed:activearchivedinactive
titlestringrequired
Title of the alert.
usage_thresholdobjectoptional
Encapsulates configuration of the alert to monitor usage on a specific [Billing Meter](https://docs.stripe.com/api/billing/meter).
defaultError response.
errorobjectrequired

Error handling

alert_type must be usage_threshold, and title must be no longer than 256 characters. usage_threshold must include gte, meter, and recurrence, with recurrence set to one_time.