Create subscription alert

Establishes a new usage-based alert for a subscription to notify merchants when consumption reaches specified thresholds. Supports multiple alert types including current billing period usage, lifetime usage, and metric-specific monitoring for both monetary amounts and consumption units.

Authorization

AuthorizationBearer <token>

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

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Read accessread
Write accesswrite

Path Parameters

external_subscription_id*string

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.

Request Body

application/json

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

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/alerts" \  -H "Content-Type: application/json" \  -d '{    "code": "storage_monetary_alert",    "metric_code": "Storage_Metrics_1753985710",    "name": "Current Monetary Usage Alert specific to a Metric",    "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"
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "dc99e3955cdd8",
  "details": [
    {
      "field": "/email",
      "value": "abc",
      "location": "body",
      "issue": "INVALID_PARAMETER_VALUE",
      "description": "The value of a field does not conform to the expected format."
    }
  ]
}

{
  "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": "[email protected]",
      "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"
}

Path Parameters

external_subscription_id*string

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.

Request Body

application/json

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

TypeScript Definitions

Use the request body type in TypeScript.

type*AlertType

Type of alert

Value in"CURRENT_USAGE_AMOUNT" | "METRIC_CURRENT_USAGE_AMOUNT" | "METRIC_CURRENT_USAGE_UNITS" | "LIFETIME_USAGE_AMOUNT"

code*string

The unique code to identify the alert.

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).

name?string

The name of the alert.

thresholds*array<>

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

curl -X POST "https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/SUB_1752779018503/alerts" \ -H "Content-Type: application/json" \ -d '{ "code": "storage_monetary_alert", "metric_code": "Storage_Metrics_1753985710", "name": "Current Monetary Usage Alert specific to a Metric", "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" }

{ "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "debug_id": "dc99e3955cdd8", "details": [ { "field": "/email", "value": "abc", "location": "body", "issue": "INVALID_PARAMETER_VALUE", "description": "The value of a field does not conform to the expected format." } ] }

{ "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": "[email protected]", "location": "body", "issue": "UNSUPPORTED_EMAIL", "description": "The email provided is not supported." } ] }

Create subscription alert

201application/json

400application/json

404application/json

422application/json

500application/json

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Create subscription alert

201application/json

400application/json

404application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`