Skip to main content
PUT
/
subscriptions
/
{external_id}
/
alerts
/
{code}
Modify subscription alert
curl --request PUT \
  --url https://api-m.paypal.com/v1/commerce/billing/subscriptions/{external_id}/alerts/{code} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "ALERT_CODE_UPDATED_1234567890",
  "name": "Updated Current Usage Alert specific to a Metric units",
  "thresholds": [
    {
      "code": "warn",
      "value": "200000.0",
      "recurring": false
    },
    {
      "code": "hard",
      "value": "250000.0",
      "recurring": false
    },
    {
      "code": "recurring",
      "value": "50000.0",
      "recurring": true
    }
  ]
}'
{
  "id": "a3c9e51d-6c0d-4cad-a029-6e5c0c08fc52",
  "external_subscription_id": "SUB_1752779018503",
  "metric": {
    "name": "Storage usage",
    "code": "Storage_Metrics_1754980238",
    "type": "METERED",
    "description": "GB of storage used in my application",
    "aggregation_type": "SUM",
    "aggregation_field": "gb",
    "field_filters": [
      {
        "key": "region",
        "values": [
          "us-west1"
        ]
      }
    ],
    "id": "0eb44a04-dc60-4d2c-aacb-90d5dbb2b048",
    "created_at": "2025-08-12T06:30:39Z"
  },
  "type": "METRIC_CURRENT_USAGE_UNITS",
  "code": "ALERT_CODE_UPDATED_1234567890",
  "name": "Updated Current Usage Alert specific to a Metric units",
  "previous_value": 0,
  "thresholds": [
    {
      "code": "warn",
      "value": "200000.0",
      "recurring": false
    },
    {
      "code": "hard",
      "value": "250000.0",
      "recurring": false
    },
    {
      "code": "recurring",
      "value": "50000.0",
      "recurring": true
    }
  ],
  "last_processed_at": "2025-08-16T09:45:00Z",
  "created_at": "2025-08-12T06:31:47Z"
}

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"

​
code
string
required

Unique identifier code for the specific alert within the subscription context. This code is customer-defined during alert creation and used for all subsequent operations on the alert.

Example:

"ALERT_CODE_1234567890"

Body

application/json

Modified alert configuration containing updated threshold values and other configurable parameters.

​
code
string

The unique code to identify the alert.

Example:

"api_calls_usage_alerts"

​
metric_code
string

The code of the metric associated with the alert. Only for alerts based on a metric.

Example:

"api_calls"

​
name
string

The name of the alert.

Example:

"Usage alerts for API calls"

​
thresholds
object[]

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

Response

Alert configuration successfully updated with the provided changes.

​
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