> ## 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. # 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. ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json get /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: get: tags: - Alerts summary: Retrieve subscription alerts description: >- Retrieves all usage-based alerts configured for a specific subscription. Use this endpoint to monitor and manage billing alerts across different consumption thresholds. operationId: GetAlertsByExternalId 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 - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' responses: '200': description: >- Successfully retrieved the collection of alerts configured for the specified subscription. content: application/json: schema: $ref: '#/components/schemas/AlertList' example: 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 '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: parameters: per_page: name: per_page in: query description: Number of records per page schema: type: integer page: name: page in: query description: Page number schema: type: integer schemas: AlertList: type: object properties: alerts: type: array items: $ref: '#/components/schemas/Alert' description: 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: $ref: '#/components/schemas/PaginationMetadata' 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' PaginationMetadata: type: object properties: total_count: type: integer total_pages: type: integer current_page: type: integer Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' 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. 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 DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. example: '2023-10-01T12:00:00Z' 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 ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string 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 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: 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 ````