Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.