Core Resources
Payment Methods
Products
Product Catalog
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Create a billing alert v1

POST /v1/billing/alerts

Creates a billing alert

Parameters

  • alert_typeenumRequired

    The type of alert to create.

    Possible enum values
    usage_threshold

    Use usage_threshold if you intend for an alert to fire when a usage threshold on a meter is crossed.

  • titlestringRequired

    The title of the alert.

    The maximum length is 256 characters.

  • usage_thresholdobject

    The configuration of the usage threshold.

Returns

Returns a billing alert

curl https://api.stripe.com/v1/billing/alerts \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "title=API Request usage alert" \
  -d alert_type=usage_threshold \
  -d "usage_threshold[gte]=10000" \
  -d "usage_threshold[meter]=mtr_12345" \
  -d "usage_threshold[recurrence]=one_time"
Response
{
  "id": "alrt_12345",
  "object": "billing.alert",
  "title": "API Request usage alert",
  "livemode": true,
  "alert_type": "usage_threshold",
  "usage_threshold": {
    "gte": 10000,
    "meter": "mtr_12345",
    "recurrence": "one_time"
  },
  "status": "active"
}

Retrieve a billing alert v1

GET /v1/billing/alerts/:id

Retrieves a billing alert given an ID

Parameters

No parameters.

Returns

Returns the alert

curl https://api.stripe.com/v1/billing/alerts/alrt_12345 \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "alrt_12345",
  "object": "billing.alert",
  "title": "API Request usage alert",
  "livemode": true,
  "alert_type": "usage_threshold",
  "usage_threshold": {
    "gte": 10000,
    "meter": "mtr_12345",
    "recurrence": "one_time"
  },
  "status": "active"
}

List billing alert notifications v1

GET /v1/billing/alerts/:id/notifications

Lists sent billing alert triggered and recovered notifications for a billing alert.

Parameters

  • customerstringRequired

    The customer to list notifications for.

More parameters

  • actionstring

  • cadencestring

  • ending_beforestring

  • limitinteger

  • meterstring

  • notified_atobject

  • starting_afterstring

  • subscriptionstring

Returns

Returns a list of billing alert notification history entries.

cURL
curl -G https://api.stripe.com/v1/billing/alerts/alrt_12345/notifications \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d customer=cus_12345
Response
{
  "object": "list",
  "data": [
    {
      "id": "threvt_12345",
      "object": "billing.alert_notification",
      "action": "triggered",
      "customer": "cus_12345",
      "notification_event": "evt_12345",
      "alert": "alrt_12345",
      "subscription": "sub_12345",
      "cadence": "monthly",
      "value": "123.45",
      "currency": "usd",
      "alert_type": "spend_threshold",
      "meter": null,
      "aggregation_period_start": null,
      "aggregation_period_end": null,
      "livemode": false,
      "notified_at": 1700000020
    }
  ]
}