Skip to main content
GET
/
subscriptions
/
{external_id}
/
alerts
Retrieve subscription alerts
curl --request GET \
  --url https://api-m.paypal.com/v1/commerce/billing/subscriptions/{external_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
  }
}

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"

Query Parameters

​
per_page
integer

Number of records per page

​
page
integer

Page number

Response

Successfully retrieved the collection of alerts configured for the specified subscription.

​
alerts
object[]

List of alerts

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"
  }
]
​
meta
object
⌘I