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 send a POST request to /v1/commerce/billing/subscriptions/{external_id}/alerts with all required request parameters. Path parameter: external_id is the subscription’s unique identifier you provided when creating 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. 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 will 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, 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

Note: 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 to manage or reference the alert in future API calls.
external_subscription_id
string		Unique identifier of the subscription linked to the alert. Use this 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:
Note: 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.
⌘I