Set up alerts and use webhooks

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.

Parameter	Action
`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"
}'

{
  "id" : "f5ca7539-e540-4d92-a416-fcece5970bf4",
  "external_subscription_id" : "SUB_1752779018503",
  "type" : "CURRENT_USAGE_AMOUNT",
  "code" : "current_cycle_monetary_usage_alert",
  "name" : "Current Cycle Monetary Usage Alert",
  "previous_value" : 0.0,
  "thresholds" : [
    {
      "code" : "warn",
      "value" : "500.0",
      "recurring" : false
    },
    {
      "code" : "hard",
      "value" : "700.0",
      "recurring" : false
    },
    {
      "code" : "recurring",
      "value" : "200.0",
      "recurring" : true
    }
  ],
  "last_processed_at" : "2025-08-16T10:04:21Z",
  "created_at" : "2025-07-31T18:28:31Z"
}

A successful call returns a 201 Created response. The response includes the following parameters:

Parameter	Description	Further 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

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.
In your server-side app code, define a webhook handler that:
- Listens to the webhook event.
- Confirms receipt of the webhook event to PayPal.
- Verifies the source of the event notification.
- Parses the webhook payload received from PayPal - it includes the alert ID, subscription ID, alert type, metric code, current value, crossed thresholds, and trigger time. See the webhook payload sample for details.
- Uses the parsed data to notify users, enforce limits, or automate business logic.

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.

​1. Create usage alert and set up thresholds

​2. Use webhooks to monitor threshold breaches

1. Create usage alert and set up thresholds

2. Use webhooks to monitor threshold breaches