Retrieve subscription alerts
curl --request GET \
--url https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/{external_subscription_id}/alerts \
--header 'Authorization: Bearer <token>'{
"alerts": [
{
"id": "7e6a89c9-ab69-4702-98f5-c245aca88080",
"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_UNITS",
"code": "storage_units_current_cycle",
"name": "Current Usage Alert specific to a Metric units",
"previous_value": 0,
"thresholds": [
{
"code": "units_used",
"value": "500000.0",
"recurring": false
}
],
"created_at": "2025-08-01T05:58:57Z"
},
{
"id": "14a42687-1814-4419-a111-76ff5792a786",
"external_subscription_id": "SUB_1752779018503",
"metric": {
"name": "Storage usage amount",
"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_amount_current_cycle",
"name": "Current Monetary Usage Alert specific to a Metric",
"previous_value": 0,
"thresholds": [
{
"code": "warn",
"value": "1000.0",
"recurring": false
}
],
"created_at": "2025-08-01T05:58:53Z"
},
{
"id": "13aac90e-927a-4203-8d42-11a388b91308",
"external_subscription_id": "SUB_1752779018503",
"type": "CURRENT_USAGE_AMOUNT",
"code": "current_usage_amount_aggregated_current_cycle",
"name": "Current Cycle Monetary Usage Alert",
"previous_value": 0,
"thresholds": [
{
"code": "hard",
"value": "9000.1",
"recurring": false
}
],
"last_processed_at": "2025-08-03T10:04:21Z",
"created_at": "2025-08-01T05:58:48Z"
},
{
"id": "f5ca7539-e540-4d92-a416-fcece5970bf4",
"external_subscription_id": "SUB_1752779018503",
"type": "LIFETIME_USAGE_AMOUNT",
"code": "lifetime_usage_alert",
"name": "Lifetime Monetary Usage Alert",
"previous_value": 0,
"thresholds": [
{
"code": "warn",
"value": "5000.0",
"recurring": false
},
{
"code": "hard",
"value": "10000.0",
"recurring": false
},
{
"code": "hard",
"value": "2000.0",
"recurring": true
}
],
"created_at": "2025-07-31T18:28:31Z"
}
],
"meta": {
"total_count": 4,
"total_pages": 1,
"current_page": 1
}
}{
"name": "<string>",
"debug_id": "<string>",
"message": "<string>",
"details": [
{
"field": "<string>",
"value": "<string>",
"location": "<string>",
"issue": "<string>",
"description": "<string>"
}
]
}{
"name": "UNPROCESSABLE_ENTITY",
"message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
"debug_id": "90957fca61718",
"details": [
{
"field": "/email",
"value": "sdfwdj@sdfs.com",
"location": "body",
"issue": "UNSUPPORTED_EMAIL",
"description": "The email provided is not supported."
}
]
}{
"name": "INTERNAL_SERVER_ERROR",
"message": "An internal server error has occurred.",
"debug_id": "90957fca61718"
}Retrieve subscription alerts
Retrieves all usage-based alerts configured for a specific subscription. Use this endpoint to monitor and manage billing alerts across different consumption thresholds.
GET
/
subscriptions
/
{external_subscription_id}
/
alerts
Retrieve subscription alerts
curl --request GET \
--url https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/{external_subscription_id}/alerts \
--header 'Authorization: Bearer <token>'{
"alerts": [
{
"id": "7e6a89c9-ab69-4702-98f5-c245aca88080",
"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_UNITS",
"code": "storage_units_current_cycle",
"name": "Current Usage Alert specific to a Metric units",
"previous_value": 0,
"thresholds": [
{
"code": "units_used",
"value": "500000.0",
"recurring": false
}
],
"created_at": "2025-08-01T05:58:57Z"
},
{
"id": "14a42687-1814-4419-a111-76ff5792a786",
"external_subscription_id": "SUB_1752779018503",
"metric": {
"name": "Storage usage amount",
"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_amount_current_cycle",
"name": "Current Monetary Usage Alert specific to a Metric",
"previous_value": 0,
"thresholds": [
{
"code": "warn",
"value": "1000.0",
"recurring": false
}
],
"created_at": "2025-08-01T05:58:53Z"
},
{
"id": "13aac90e-927a-4203-8d42-11a388b91308",
"external_subscription_id": "SUB_1752779018503",
"type": "CURRENT_USAGE_AMOUNT",
"code": "current_usage_amount_aggregated_current_cycle",
"name": "Current Cycle Monetary Usage Alert",
"previous_value": 0,
"thresholds": [
{
"code": "hard",
"value": "9000.1",
"recurring": false
}
],
"last_processed_at": "2025-08-03T10:04:21Z",
"created_at": "2025-08-01T05:58:48Z"
},
{
"id": "f5ca7539-e540-4d92-a416-fcece5970bf4",
"external_subscription_id": "SUB_1752779018503",
"type": "LIFETIME_USAGE_AMOUNT",
"code": "lifetime_usage_alert",
"name": "Lifetime Monetary Usage Alert",
"previous_value": 0,
"thresholds": [
{
"code": "warn",
"value": "5000.0",
"recurring": false
},
{
"code": "hard",
"value": "10000.0",
"recurring": false
},
{
"code": "hard",
"value": "2000.0",
"recurring": true
}
],
"created_at": "2025-07-31T18:28:31Z"
}
],
"meta": {
"total_count": 4,
"total_pages": 1,
"current_page": 1
}
}{
"name": "<string>",
"debug_id": "<string>",
"message": "<string>",
"details": [
{
"field": "<string>",
"value": "<string>",
"location": "<string>",
"issue": "<string>",
"description": "<string>"
}
]
}{
"name": "UNPROCESSABLE_ENTITY",
"message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
"debug_id": "90957fca61718",
"details": [
{
"field": "/email",
"value": "sdfwdj@sdfs.com",
"location": "body",
"issue": "UNSUPPORTED_EMAIL",
"description": "The email provided is not supported."
}
]
}{
"name": "INTERNAL_SERVER_ERROR",
"message": "An internal server error has occurred.",
"debug_id": "90957fca61718"
}Authorizations
Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.
Path Parameters
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"
Response
Successfully retrieved the collection of alerts configured for the specified subscription.
List of alerts
Show child attributes
Show child attributes
Example:
[
{
"id": "alert_01H3YT8P7Q5R3S1T2U0V4W9X8",
"external_subscription_id": "sub_external_12345",
"type": "CURRENT_USAGE_AMOUNT",
"code": "current_usage_monetary_alert",
"name": "Monetary Usage Alert",
"previous_value": 1000,
"last_processed_at": "2025-05-19T10:04:21Z",
"thresholds": [
{
"code": "warn",
"recurring": false,
"value": "99.0"
}
],
"created_at": "2025-04-20T10:00:00Z"
}
]
Show child attributes
Show child attributes
Was this page helpful?
⌘I