Skip to main content
Limited Release
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. Include the following parameters: Path parameter: external_subscription_id is the external_id you provided when you created the subscription.
ParameterAction
type
Required, string		Set the type of alert to create.

Possible values:
CURRENT_USAGE_AMOUNT: Total usage amount for the current billing cycle
METRIC_CURRENT_USAGE_AMOUNT: Monetary usage of a specific metric for the current billing cycle
METRIC_CURRENT_USAGE_UNITS: Units consumed for a specific metric in the current billing cycle
LIFETIME_USAGE_AMOUNT: Total usage amount across the entire subscription duration
code
Required, string		Set a unique code to identify the alert.
metric_code
string		Set to the code returned when you created the metric. Required only for metric-based alert types (METRIC_CURRENT_USAGE_AMOUNT and METRIC_CURRENT_USAGE_UNITS).
name
string		Provide a name for the alert.
thresholds[]
Required, array		Provide a list of thresholds that trigger the alert. At least one threshold is required.
thresholds[].code
string		Set a user-defined identifier to distinguish between thresholds (for example, warn, hard, recurring).
thresholds[].value
Required when thresholds[] provided, string		Set the value that triggers this alert. Must be a positive numeric string.
thresholds[].recurring
boolean		Set to true to trigger alerts every time usage exceeds the last non-recurring threshold by this value. Only one recurring threshold is permitted per alert.
For information on all parameters, see API reference. 
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"
}'
A successful call returns a 201 Created response. The response includes the following parameters:
ParameterDescriptionFurther action
id
string		Unique identifier for the alert.Use this id 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.
For information on all parameters, see API reference.

​
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.