Core Resources
Payment Methods
Money Management
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
Tax Reporting
Forwarding
Privacy
Webhooks

Alerts v1

A billing alert is a resource that notifies you when a certain usage threshold on a meter is crossed. For example, you might create a billing alert to notify you when a certain user made 100 API requests.

Was this section helpful?YesNo
Create a billing alert
POST/v1/billing/alerts
Retrieve a billing alert
GET/v1/billing/alerts/:id
List billing alert notifications
GET/v1/billing/alerts/:id/notifications
List billing alerts
GET/v1/billing/alerts
Activate a billing alert
POST/v1/billing/alerts/:id/activate
Archive a billing alert
POST/v1/billing/alerts/:id/archive
Deactivate a billing alert
POST/v1/billing/alerts/:id/deactivate

The Alert object v1

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "billing.alert"

    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

    If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

  • statusnullable enum

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

    Possible enum values
    active
    archived
    inactive

  • 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"
}

The Billing Alert Notification object v1

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "billing.alert_notification"

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

  • actionenum

    Whether the alert was triggered or recovered.

    Possible enum values
    recovered

    The alert recovered below the threshold and a notification was sent.

    triggered

    The alert threshold was crossed and a notification was sent.

  • aggregation_period_endnullable timestamp

    End of the aggregation period for which this notification was sent. Only present for usage threshold alerts.

  • aggregation_period_startnullable timestamp

    Start of the aggregation period for which this notification was sent. Only present for usage threshold alerts.

  • alertstring

    ID of the billing alert that generated this notification.

  • alert_typeenum

    The type of billing alert that generated this notification.

    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.

  • billing_groupnullable string

    The billing group associated with this notification. Only present for spend threshold alerts grouped by billing group.

  • cadencenullable string

    The cadence associated with this notification. Only present for spend threshold alerts grouped by cadence.

  • currencynullable string

    Three-letter ISO currency code for the value, in lowercase. Only present for spend and credit balance threshold alerts.

  • customerstring

    ID of the customer for which the alert notification was sent.

  • livemodeboolean

    The value is true for objects in live mode and false for objects in a sandbox. For accounts that still have access to legacy test mode, the value is also false for objects in that mode.

  • meternullable string

    ID of the billing meter associated with this notification. Only present for usage threshold alerts.

  • notification_eventstring

    ID of the event delivered for this notification. Retrievable via the Events API for a limited time; for long-term audit scenarios, capture the full event payload at webhook delivery time.

  • notified_attimestamp

    Time at which the notification was sent. Measured in seconds since the Unix epoch.

  • subscriptionnullable string

    ID of the subscription associated with this notification. Only present for spend threshold alerts grouped by subscription.

  • valuestring

    The value that triggered the alert. This may be a decimal string for custom pricing unit alerts. For usage threshold alerts, this is the meter event count. For credit balance and spend threshold alerts, this is the amount in the smallest currency unit.

The Billing Alert Notification object
{
  "id": "threvt_12345",
  "object": "billing.alert_notification",
  "action": "triggered",
  "customer": "cus_12345",
  "notification_event": "evt_12345",
  "alert": "alrt_12345",
  "subscription": null,
  "cadence": null,
  "value": "12345",
  "currency": null,
  "alert_type": "usage_threshold",
  "meter": "mtr_12345",
  "aggregation_period_start": 1698796800,
  "aggregation_period_end": 1701388800,
  "livemode": false,
  "notified_at": 1700000020
}