PApaypal
Alerts

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.

post/subscriptions/{external_subscription_id}/alerts

Request

Path parameters

external_subscription_idstring required
Example:SUB_1752779018503

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

type'CURRENT_USAGE_AMOUNT' | 'METRIC_CURRENT_USAGE_AMOUNT' | 'METRIC_CURRENT_USAGE_UNITS' | 'LIFETIME_USAGE_AMOUNT' required

Type of alert

codestring required

The unique code to identify the alert.

metric_codestring

The code of the metric associated with the alert. Required for metric-specific alert types (METRIC_CURRENT_USAGE_AMOUNT and METRIC_CURRENT_USAGE_UNITS).

namestring

The name of the alert.

Example request

{
  "type": "CURRENT_USAGE_AMOUNT",
  "code": "storage_metric_alert",
  "metric_code": "storage_metric",
  "name": "Usage Warning at 80%",
  "thresholds": [
    {
      "code": "warn",
      "value": "80.0"
    }
  ]
}

Response

Alert configuration successfully created and activated for the subscription.

idstring

Unique identifier for the alert, assigned by the system upon creation.

external_subscription_idstring

External identifier of the subscription that this alert is monitoring.

type'CURRENT_USAGE_AMOUNT' | 'METRIC_CURRENT_USAGE_AMOUNT' | 'METRIC_CURRENT_USAGE_UNITS' | 'LIFETIME_USAGE_AMOUNT'

Type of alert

codestring

The unique code to identify the alert within a subscription. Used in API endpoints for operations on specific alerts.

namestring

Human-readable display name for the alert. Used for identification in user interfaces.

previous_valuenumber

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.

last_processed_atstring date-time

Date and time in ISO 8601 format.

created_atstring date-time

Date and time in ISO 8601 format.

Example response

{
  "id": "fb2d17b8-c66d-4269-b38e-9d62d37812e3",
  "external_subscription_id": "sub_external_12345",
  "metric": {
    "type": "METERED",
    "aggregation_type": "SUM",
    "created_at": "2023-10-01T12:00:00Z",
    "updated_at": "2023-10-01T12:00:00Z"
  },
  "type": "CURRENT_USAGE_AMOUNT",
  "code": "tokens_usage_alert",
  "name": "Tokens Usage Alert",
  "previous_value": 75.52,
  "last_processed_at": "2023-10-01T12:00:00Z",
  "thresholds": [
    {
      "code": "warn",
      "value": "80",
      "recurring": false
    }
  ],
  "created_at": "2023-10-01T12:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.