> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json post /subscriptions/{external_subscription_id}/alerts openapi: 3.0.1 info: title: Usage Based Billing API version: 1.0.0 description: An Orchestrator for Usage Based Billing and Payments servers: - url: https://api-m.sandbox.paypal.com/v1/commerce/billing security: - BearerAuth: - read - write tags: - name: Alerts description: API endpoints for managing subscription alerts - name: Events description: API endpoints for managing events - name: Metrics description: API endpoints for metrics and usage data - name: Merchant Activation description: API endpoint for merchant activation - name: Credit Notes description: API endpoints for credit notes management - name: Customers description: API endpoints for customer management - name: Invoices description: API endpoints for invoice management - name: Plans description: API endpoints for subscription plans - name: Subscriptions description: API endpoints for subscriptions - name: Wallets description: API endpoints for wallet management - name: Taxes description: API endpoints for tax management - name: Billing Entities description: API endpoints for billing entities - name: Features description: API endpoints for managing features and privileges - name: Entitlements description: API endpoints for managing plan and subscription entitlements paths: /subscriptions/{external_subscription_id}/alerts: post: tags: - Alerts summary: Create subscription alert description: >- 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. operationId: CreateAlert parameters: - name: external_subscription_id in: path required: true description: >- 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. schema: type: string example: SUB_1752779018503 requestBody: required: true description: >- Complete alert configuration including type, thresholds, and optional metric information. The alert type determines which fields are required. content: application/json: schema: $ref: '#/components/schemas/AlertInput' example: 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 responses: '201': description: >- Alert configuration successfully created and activated for the subscription. content: application/json: schema: $ref: '#/components/schemas/Alert' example: 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' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: schemas: AlertInput: type: object required: - type - code - thresholds properties: type: $ref: '#/components/schemas/AlertType' code: type: string description: The unique code to identify the alert. example: storage_metric_alert metric_code: type: string description: >- The code of the metric associated with the alert. Required for metric-specific alert types (METRIC_CURRENT_USAGE_AMOUNT and METRIC_CURRENT_USAGE_UNITS). example: storage_metric name: type: string description: The name of the alert. example: Usage Warning at 80% thresholds: type: array items: $ref: '#/components/schemas/AlertThreshold' description: >- List of thresholds that will trigger this alert. At least one threshold is required. Alert: type: object properties: id: type: string description: >- Unique identifier for the alert, assigned by the system upon creation. example: fb2d17b8-c66d-4269-b38e-9d62d37812e3 external_subscription_id: type: string description: >- External identifier of the subscription that this alert is monitoring. example: sub_external_12345 metric: $ref: '#/components/schemas/MetricResponse' type: $ref: '#/components/schemas/AlertType' code: type: string description: >- The unique code to identify the alert within a subscription. Used in API endpoints for operations on specific alerts. example: tokens_usage_alert name: type: string description: >- Human-readable display name for the alert. Used for identification in user interfaces. example: Tokens Usage Alert previous_value: type: number description: >- 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: allOf: - $ref: '#/components/schemas/DateTimeWithZone' description: >- 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. example: '2025-05-01T12:00:00Z' thresholds: type: array items: $ref: '#/components/schemas/AlertThreshold' description: >- List of configured thresholds that trigger this alert. Includes both one-time and recurring thresholds. example: - code: warn value: '80' recurring: false created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' description: The date and time when the alert was created. example: '2025-04-21T10:00:00Z' AlertType: type: string enum: - CURRENT_USAGE_AMOUNT - METRIC_CURRENT_USAGE_AMOUNT - METRIC_CURRENT_USAGE_UNITS - LIFETIME_USAGE_AMOUNT description: Type of alert x-enum-varnames: - CURRENT_USAGE_AMOUNT - METRIC_CURRENT_USAGE_AMOUNT - METRIC_CURRENT_USAGE_UNITS - LIFETIME_USAGE_AMOUNT x-enum-descriptions: - Alert based on current usage amount - Alert based on metric current usage amount - Alert based on metric current usage units - Alert based on lifetime usage amount example: CURRENT_USAGE_AMOUNT AlertThreshold: type: object required: - value properties: code: type: string description: >- Identifier for this threshold. Used to distinguish between different thresholds. example: warn value: type: string pattern: ^[0-9]+\.?[0-9]*$ description: >- A value that should trigger this alert. Must be a positive numeric string that can include a decimal point. example: '80.0' recurring: type: boolean description: >- When true, enables retriggering of alerts at specified intervals after the last non-recurring threshold is exceeded. For example, with non-recurring thresholds at 500 and 1000, and a recurring threshold of 200, alerts will fire at 500, 1000, then every 200 thereafter (1200, 1400, etc.). Only one recurring threshold permitted per alert. example: false MetricResponse: type: object required: - id - name - code - aggregation_type - created_at allOf: - $ref: '#/components/schemas/MetricBase' - type: object properties: id: type: string description: >- Unique identifier of the metric, automatically generated by the system upon creation. This ID is used internally to track the metric and cannot be modified. created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' description: >- The date and time when the metric was created. ISO 8601 format with timezone. updated_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' description: >- The date and time when the metric was last updated. ISO 8601 format with timezone. DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. example: '2023-10-01T12:00:00Z' Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' MetricBase: type: object properties: name: type: string description: >- Descriptive name of the metric that represents a pricing component of your application. This is primarily used for display purposes in the user interface. code: type: string description: >- Unique code used to identify the metric within your system. This code is used in API requests to associate events with the correct metric and must be unique across all metrics. Once created, this code cannot be changed. type: $ref: '#/components/schemas/MetricType' description: type: string description: >- Optional detailed description of the metric that provides additional context about what the metric measures and how it's used. This information is for internal use and helps document the purpose of the metric. aggregation_type: $ref: '#/components/schemas/MetricAggregationType' aggregation_field: type: string description: >- Property name within the event payload that will be used for aggregating usage data. This field specifies which value from the event should be used for calculations. It is required for aggregation types like 'SUM', 'MAX', and other types that operate on values, but not required for 'COUNT' aggregation. field_filters: type: array items: type: object properties: key: type: string description: >- Property name within the event payload that will be used for filtering. This allows you to segment usage data based on specific event properties, such as region, tier, or any other dimension you track. values: type: array items: type: string description: >- Array of specific values that the system should match against the filter key. Only events with matching key-value pairs will be included in the metric calculations. This enables differentiated pricing based on dimensions like region, environment, or other custom properties. required: - key - values ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string MetricType: type: string default: RECURRING enum: - METERED - RECURRING description: >- Type of metric, either 'metered' for usage-based or 'recurring' for fixed periodic charges. example: METERED x-enum-varnames: - METERED - RECURRING x-enum-descriptions: - Usage-based metric that charges based on the amount used. - Fixed periodic charge that recurs at specified intervals. MetricAggregationType: type: string nullable: true enum: - COUNT - SUM - MAX - COUNT_DISTINCT - LATEST x-enum-varnames: - COUNT - SUM - MAX - COUNT_DISTINCT - LATEST x-enum-descriptions: - Count the number of events - Sum the values of a numeric field - Find the maximum value of a numeric field - Count the number of distinct values - Use the latest value description: Aggregation type for the metric example: SUM responses: BadRequest: description: Bad Request - Invalid input data content: application/json: schema: $ref: '#/components/schemas/Error' example: 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. NotFound: description: Resource Not Found. content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: Bad Request - Invalid input data content: application/json: schema: $ref: '#/components/schemas/Error' example: 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. InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/Error' example: name: INTERNAL_SERVER_ERROR message: An internal server error has occurred. debug_id: 90957fca61718 securitySchemes: BearerAuth: type: oauth2 description: >- Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header. flows: clientCredentials: tokenUrl: https://api-m.sandbox.paypal.com/v1/oauth2/token scopes: read: Read access write: Write access ````