Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

The Alert object 

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • alert_typeenum

    Defines the type of the alert.

    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.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • statusnullable enum

    Status of the alert. This can be active, inactive or archived.

  • titlestring

    Title of the alert.

  • usage_thresholdnullable object

    Encapsulates configuration of the alert to monitor usage on a specific Billing Meter.

The Alert object
{
  "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"
}

Create a billing alert 

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.

  • usage_thresholdobject

    The configuration of the usage threshold.

Returns

Returns a billing alert

POST /v1/billing/alerts
curl https://api.stripe.com/v1/billing/alerts \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_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 

Retrieves a billing alert given an ID

Parameters

No parameters.

Returns

Returns the alert

GET /v1/billing/alerts/:id
curl https://api.stripe.com/v1/billing/alerts/alrt_12345 \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_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 alerts 

Lists billing active and inactive alerts

Parameters

  • alert_typeenum

    Filter results to only include this type of alert.

    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.

  • meterstring

    Filter results to only include alerts with the given meter.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

Returns a list of billing alerts

GET /v1/billing/alerts
curl https://api.stripe.com/v1/billing/alerts \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "data": [
    {
      "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"
    },
    {
      "id": "alrt_67890",
      "object": "billing.alert",
      "title": "API Request usage alert",
      "livemode": true,
      "alert_type": "usage_threshold",
      "usage_threshold": {
        "gte": 120,
        "meter": "mtr_67890",
        "recurrence": "one_time"
      },
      "status": "active"
    }
  ]
}

Activate a billing alert 

Reactivates this alert, allowing it to trigger again.

Parameters

No parameters.

Returns

Returns the alert with its updated status.

POST /v1/billing/alerts/:id/activate
curl -X POST https://api.stripe.com/v1/billing/alerts/alrt_12345/activate \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_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"
}