Skip to main content
GET
/
subscriptions
/
{external_id}
/
alerts
/
{code}
Retrieve specific subscription alert
curl --request GET \
  --url https://api-m.paypal.com/v1/commerce/billing/subscriptions/{external_id}/alerts/{code} \
  --header 'Authorization: Bearer <token>'
{
  "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_1234567890",
  "name": "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"

Response

Successfully retrieved the detailed configuration and current status of the specified alert.

​
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