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

# Set up alerts and use webhooks

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

You can [set up usage alert thresholds](#1-create-usage-alert-and-set-up-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 <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> 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 <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions" target="_blank" rel="noopener noreferrer">created the subscription</a>.

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                                                         | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                           | Set the type of alert to create.<br /><br /><b>Possible values:</b><br />`CURRENT_USAGE_AMOUNT`: Total usage amount for the current billing cycle<br />`METRIC_CURRENT_USAGE_AMOUNT`: Monetary usage of a specific metric for the current billing cycle<br />`METRIC_CURRENT_USAGE_UNITS`: Units consumed for a specific metric in the current billing cycle<br />`LIFETIME_USAGE_AMOUNT`: Total usage amount across the entire subscription duration |
| `code`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                           | Set a unique code to identify the alert.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `metric_code`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                       | Set to the `code` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics" target="_blank" rel="noopener noreferrer">created the metric</a>. Required only for metric-based alert types (`METRIC_CURRENT_USAGE_AMOUNT` and `METRIC_CURRENT_USAGE_UNITS`).                                                                                                                                               |
| `name`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                              | Provide a name for the alert.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `thresholds[]`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                    | Provide a list of thresholds that trigger the alert. At least one threshold is required.                                                                                                                                                                                                                                                                                                                                                              |
| `thresholds[].code`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                 | Set a user-defined identifier to distinguish between thresholds (for example, `warn`, `hard`, `recurring`).                                                                                                                                                                                                                                                                                                                                           |
| `thresholds[].value`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required when thresholds\[] provided</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set the value that triggers this alert. Must be a positive numeric string.                                                                                                                                                                                                                                                                                                                                                                            |
| `thresholds[].recurring`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>boolean</span>                                                                                           | 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 <a href="/reference/api/rest/alerts/create-subscription-alert" target="_blank" rel="noopener noreferrer">API reference</a>.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  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"
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

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

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                | <span style={{textAlign: 'left', display: 'block'}}>Description</span> | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>                                |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                       | Unique identifier for the alert.                                       | Use this `id` when managing or referencing the alert.                                                    |
| `external_subscription_id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | 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 <a href="/reference/api/rest/alerts/create-subscription-alert" target="_blank" rel="noopener noreferrer">API reference</a>.

## 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.
   * <a href="https://developer.paypal.com/docs/api/webhooks/v1/" target="_blank" rel="noopener noreferrer">Webhooks management API</a>.
2. In your server-side app code, define a webhook handler that:
   * <a href="https://developer.paypal.com/api/rest/webhooks/rest/#link-subscribingalistenerurl" target="_blank" rel="noopener noreferrer">Listens to the webhook event</a>.
   * <a href="https://developer.paypal.com/api/rest/webhooks/#link-receivingthemessage" target="_blank" rel="noopener noreferrer">Confirms receipt of the webhook event to PayPal</a>.
   * <a href="https://developer.paypal.com/api/rest/webhooks/#link-verifyingthemessagereceived" target="_blank" rel="noopener noreferrer">Verifies the source of the event notification</a>.
   * 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 <a href="/limited-release/usage-based-billing/reference/webhooks-reference#sample-webhook-payloads" target="_blank" rel="noopener noreferrer">webhook payload sample</a> for details.
   * Uses the parsed data to notify users, enforce limits, or automate business logic.

<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 <a href="/limited-release/usage-based-billing/reference/webhooks-reference" target="_blank" rel="noopener noreferrer">Webhooks reference</a>.
</Note>