Skip to main content
You can set up usage alert thresholds for your subscriptions and use webhooks for usage monitoring. PayPal automatically sends real-time alerts to your application the moment a threshold is breached. You can act instantly—notify customers, enforce limits, or automate business processes—based on real-time usage events.

​
1. Create usage alert and set up thresholds

Use a valid access token and make a POST call to the /v1/commerce/billing/subscriptions/{external_subscription_id}/alerts endpoint with all required request parameters. Path parameter: external_subscription_id is the external_id you provided when you created the subscription. On successful alert creation, the PayPal server returns an alert ID. 
curl -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/alerts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
    "code" : "current_cycle_monetary_usage_alert",
    "name" : "Current Cycle Monetary Usage Alert",
    "thresholds" : [
        {
            "code" : "warn",
            "recurring" : false,
            "value" : "500"
        },
        {
            "code" : "hard",
            "recurring" : false,
            "value" : "700"
        },
        {
            "code" : "recurring",
            "recurring" : true,
            "value" : "200"
        }
    ],
    "type" : "CURRENT_USAGE_AMOUNT"
}'

​
Request parameters

Parameter nameDescription
type
Required, string		Type of alert to create.

Possible values:
CURRENT_USAGE_AMOUNT: Alert on total usage amount for the current billing cycle
METRIC_CURRENT_USAGE_AMOUNT: Alert on monetary usage of a specific metric for the current billing cycle
METRIC_CURRENT_USAGE_UNITS: Alert on units consumed for a specific metric in the current billing cycle
LIFETIME_USAGE_AMOUNT: Alert on total usage amount across the entire subscription duration
code
Required, string		Unique code to identify the alert.
metric_code
string		Identifier of the metric associated with the alert. Use the code you provided when you created the metric. Required only for metric-based alert types (METRIC_CURRENT_USAGE_AMOUNT and METRIC_CURRENT_USAGE_UNITS).
name
string		Name of the alert.
thresholds[]
Required, array		List of thresholds that trigger the alert. At least one threshold is required. Includes both one-time and recurring thresholds.
thresholds[].code
string		User-defined identifier for the threshold. Used to distinguish between different thresholds (for example, warn, hard, recurring).
thresholds[].value
Required when thresholds[] provided, string		Value that should trigger this alert. Must be a positive numeric string that can include a decimal point.
thresholds[].recurring
boolean		Specifies whether the threshold is recurring. When true, alerts are triggered every time the usage exceeds the last non-recurring threshold by this threshold’s value. Only one recurring threshold is permitted per alert.

​
Response parameters

This section documents only the response parameters relevant for the next step. For the exhaustive list of response fields, see API reference.
Parameter nameDescription and further action
id
string		Unique identifier for the alert.
Use this id in future operations, such as when managing or referencing the alert.
external_subscription_id
string		Unique identifier of the subscription linked to the alert.
Use this external_subscription_id to fetch subscription details or list all alerts for a subscription.

​
2. Use webhooks to monitor threshold breaches

  1. Subscribe to the USAGE-BILLING.SUBSCRIPTION-ALERT.TRIGGERED event through one of the following means:
    • PayPal developer account: Log in to your account, go to App details page > Features > Webhooks, and subscribe to the webhook event.
    • Webhooks management API.
  2. In your server-side app code, define a webhook handler that:
You can also subscribe to webhooks for wallet, invoice, credit note, and subscription lifecycle events. For the complete list of webhook events and sample payloads, see Webhooks reference.