Skip to main content
POST
/
subscriptions
/
{external_id}
/
alerts
Create subscription alert
curl --request POST \
  --url https://api-m.paypal.com/v1/commerce/billing/subscriptions/{external_id}/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "storage_monetary_alert",
  "thresholds": [
    {
      "code": "warn",
      "recurring": false,
      "value": "1000"
    }
  ],
  "type": "METRIC_CURRENT_USAGE_AMOUNT"
}'
{
  "id": "14a42687-1814-4419-a111-76ff5792a786",
  "external_subscription_id": "SUB_1752779018503",
  "metric": {
    "name": "Storage usage",
    "code": "Storage_Metrics_1753985710",
    "type": "METERED",
    "description": "GB of storage used in my application",
    "aggregation_type": "SUM",
    "aggregation_field": "gb",
    "field_filters": [
      {
        "key": "region",
        "values": [
          "us-west1"
        ]
      }
    ],
    "id": "1e421308-7ead-4aef-b527-64dd05569668",
    "created_at": "2025-07-31T18:15:12Z"
  },
  "type": "METRIC_CURRENT_USAGE_AMOUNT",
  "code": "storage_monetary_alert",
  "name": "Current Monetary Usage Alert specific to a Metric",
  "previous_value": 0,
  "thresholds": [
    {
      "code": "warn",
      "value": "1000.0",
      "recurring": false
    }
  ],
  "last_processed_at": "2025-08-01T06:15:00Z",
  "created_at": "2025-08-01T05:58:53Z"
}

Authorizations

​
Authorization
string
header
required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Path Parameters

​
external_id
string
required

Unique external identifier for the subscription. This ID is used to track the subscription across systems and must be provided to access subscription-specific alerts.

Example:

"SUB_1752779018503"

Body

application/json

Complete alert configuration including type, thresholds, and optional metric information. The alert type determines which fields are required.

​
type
enum<string>
required

Type of alert

Available options:
CURRENT_USAGE_AMOUNT,
METRIC_CURRENT_USAGE_AMOUNT,
METRIC_CURRENT_USAGE_UNITS,
LIFETIME_USAGE_AMOUNT
Example:

"CURRENT_USAGE_AMOUNT"

​
code
string
required

The unique code to identify the alert.

Example:

"storage_metric_alert"

​
thresholds
object[]
required

List of thresholds that will trigger this alert. At least one threshold is required.

​
metric_code
string

The code of the metric associated with the alert. Required for metric-specific alert types (METRIC_CURRENT_USAGE_AMOUNT and METRIC_CURRENT_USAGE_UNITS).

Example:

"storage_metric"

​
name
string

The name of the alert.

Example:

"Usage Warning at 80%"

Response

Alert configuration successfully created and activated for the subscription.

​
id
string

Unique identifier for the alert, assigned by the system upon creation.

Example:

"fb2d17b8-c66d-4269-b38e-9d62d37812e3"

​
external_subscription_id
string

External identifier of the subscription that this alert is monitoring.

Example:

"sub_external_12345"

​
metric
object
​
type
enum<string>

Type of alert

Available options:
CURRENT_USAGE_AMOUNT,
METRIC_CURRENT_USAGE_AMOUNT,
METRIC_CURRENT_USAGE_UNITS,
LIFETIME_USAGE_AMOUNT
Example:

"CURRENT_USAGE_AMOUNT"

​
code
string

The unique code to identify the alert within a subscription. Used in API endpoints for operations on specific alerts.

Example:

"tokens_usage_alert"

​
name
string

Human-readable display name for the alert. Used for identification in user interfaces.

Example:

"Tokens Usage Alert"

​
previous_value
number

The usage value from the last time this alert was evaluated. For monetary alerts, this represents currency amount; for unit alerts, this represents consumed units.

Example:

75.52

​
last_processed_at
string<date-time>

The date and time when this alert was last evaluated by the system. Null for newly created alerts that haven't been processed yet. The system evaluates alerts at regular intervals (typically every 5 minutes) to check if usage has crossed any configured thresholds. Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

​
thresholds
object[]

List of configured thresholds that trigger this alert. Includes both one-time and recurring thresholds.

Example:
[
  {
    "code": "warn",
    "value": "80",
    "recurring": false
  }
]
​
created_at
string<date-time>

The date and time when the alert was created. Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

⌘I