--- title: "Modify subscription alert" method: PUT path: "/subscriptions/{external_subscription_id}/alerts/{alert_code}" tags: ["Alerts"] --- # Modify subscription alert `PUT /subscriptions/{external_subscription_id}/alerts/{alert_code}` ## Request - Base URL: `https://api-m.sandbox.paypal.com` - URL: `https://api-m.sandbox.paypal.com/subscriptions/{external_subscription_id}/alerts/{alert_code}` - Auth: OAuth 2 - Client credentials - Token URL: `/api/oauth-proxy` scopes: `read`, `write` - TypeScript: (a function with typed inputs; its response is checked against the schema) Updates the configuration of an existing subscription alert. ## Path parameters - `external_subscription_id` string, required - `alert_code` string, required ## Request body - AlertUpdateInput - `code` string: The unique code to identify the alert. - `metric_code` string: The code of the metric associated with the alert. Only for alerts based on a metric. - `name` string: The name of the alert. - `thresholds` AlertThreshold[]: List of thresholds that will trigger this alert. At least one threshold is required. - `code` string: Identifier for this threshold. Used to distinguish between different thresholds. - `value` string, required: A value that should trigger this alert. Must be a positive numeric string that can include a decimal point. - `recurring` boolean: 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. ## Response `200` Alert configuration successfully updated with the provided changes. - Alert - `id` string: Unique identifier for the alert, assigned by the system upon creation. - `external_subscription_id` string: External identifier of the subscription that this alert is monitoring. - `metric` MetricResponse - `name` string, required: 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` string, required: 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` 'METERED' | 'RECURRING': Type of metric, either 'metered' for usage-based or 'recurring' for fixed periodic charges. - `description` string: 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` 'COUNT' | 'SUM' | 'MAX' | 'COUNT_DISTINCT' | 'LATEST', nullable, required: Aggregation type for the metric - `aggregation_field` string: 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` object[] - `key` string, required: 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` string[], required: 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. - `id` string, required: 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` string, date-time, required: Date and time in ISO 8601 format. - `updated_at` string, date-time: Date and time in ISO 8601 format. - `type` 'CURRENT_USAGE_AMOUNT' | 'METRIC_CURRENT_USAGE_AMOUNT' | 'METRIC_CURRENT_USAGE_UNITS' | 'LIFETIME_USAGE_AMOUNT': Type of alert - `code` string: The unique code to identify the alert within a subscription. Used in API endpoints for operations on specific alerts. - `name` string: Human-readable display name for the alert. Used for identification in user interfaces. - `previous_value` number: 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_at` string, date-time: Date and time in ISO 8601 format. - `thresholds` AlertThreshold[]: List of configured thresholds that trigger this alert. Includes both one-time and recurring thresholds. - `code` string: Identifier for this threshold. Used to distinguish between different thresholds. - `value` string, required: A value that should trigger this alert. Must be a positive numeric string that can include a decimal point. - `recurring` boolean: 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. - `created_at` string, date-time: Date and time in ISO 8601 format. ## Other responses - `400`: Bad Request - Invalid input data - `404`: Resource Not Found. - `422`: Bad Request - Invalid input data - `500`: Internal Server Error - An unexpected error occurred --- [API](https://skmtc.dev/paypal/apis/usage-based-billing-api.md) - [All operations](https://skmtc.dev/paypal/apis/usage-based-billing-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paypal/apis/usage-based-billing-api/revisions/22fb46514ac4?raw)