stripe 22.4.0 → 22.5.0-alpha.2

package/cjs/resources/Billing/Alerts.d.ts

@@ -1,7 +1,8 @@
 import { StripeResource } from '../../StripeResource.js';
-import { Meter } from './Meters.js';
+import { AlertNotification } from './AlertNotifications.js';
 import { Customer } from './../Customers.js';
-import { PaginationParams, OtherString } from '../../shared.js';
+import { Meter } from './Meters.js';
+import { OtherString, Decimal, PaginationParams, RangeQueryParam, Metadata } from '../../shared.js';
 import { RequestOptions, ApiListPromise, Response } from '../../lib.js';
 export declare class AlertResource extends StripeResource {
     /**
@@ -28,6 +29,10 @@ export declare class AlertResource extends StripeResource {
      * Deactivates this alert, preventing it from triggering.
      */
     deactivate(id: string, params?: Billing.AlertDeactivateParams, options?: RequestOptions): Promise<Response<Alert>>;
+    /**
+     * Lists sent billing alert triggered and recovered notifications for a billing alert.
+     */
+    listNotifications(id: string, params: Billing.AlertListNotificationsParams, options?: RequestOptions): ApiListPromise<AlertNotification>;
 }
 export interface Alert {
     /**
@@ -41,11 +46,19 @@ export interface Alert {
     /**
      * Defines the type of the alert.
      */
-    alert_type: 'usage_threshold';
+    alert_type: Alert.AlertType;
+    /**
+     * Encapsulates configuration of the alert to monitor billing credit balance.
+     */
+    credit_balance_threshold?: Alert.CreditBalanceThreshold | null;
     /**
      * If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
      */
     livemode: boolean;
+    /**
+     * Encapsulates the alert's configuration to monitor spend on pricing plan subscriptions.
+     */
+    spend_threshold?: Alert.SpendThreshold | null;
     /**
      * Status of the alert. This can be active, inactive or archived.
      */
@@ -60,6 +73,32 @@ export interface Alert {
     usage_threshold: Alert.UsageThreshold | null;
 }
 export declare namespace Alert {
+    type AlertType = 'credit_balance_threshold' | 'spend_threshold' | 'usage_threshold' | OtherString;
+    interface CreditBalanceThreshold {
+        /**
+         * The filters allow limiting the scope of this credit balance alert. You must specify only a customer filter at this time.
+         */
+        filters: Array<CreditBalanceThreshold.Filter> | null;
+        lte: CreditBalanceThreshold.Lte;
+    }
+    interface SpendThreshold {
+        /**
+         * Defines the period over which spend is aggregated.
+         */
+        aggregation_period: 'billing';
+        /**
+         * Filters to scope the spend calculation.
+         */
+        filters: SpendThreshold.Filters | null;
+        /**
+         * Defines the granularity of spend aggregation.
+         */
+        group_by: SpendThreshold.GroupBy | null;
+        /**
+         * The threshold value configuration for a spend threshold alert.
+         */
+        gte: SpendThreshold.Gte;
+    }
     type Status = 'active' | 'archived' | 'inactive' | OtherString;
     interface UsageThreshold {
         /**
@@ -79,6 +118,173 @@ export declare namespace Alert {
          */
         recurrence: 'one_time';
     }
+    namespace CreditBalanceThreshold {
+        interface Filter {
+            /**
+             * Limit the scope of the alert to this customer ID
+             */
+            customer: string | Customer | null;
+            type: Filter.Type;
+        }
+        interface Lte {
+            /**
+             * The type of this balance. We currently only support `monetary` amounts.
+             */
+            balance_type: Lte.BalanceType;
+            /**
+             * The custom pricing unit amount.
+             */
+            custom_pricing_unit?: Lte.CustomPricingUnit | null;
+            /**
+             * The monetary amount.
+             */
+            monetary: Lte.Monetary | null;
+        }
+        namespace Filter {
+            type Type = 'customer' | 'tenant' | OtherString;
+        }
+        namespace Lte {
+            type BalanceType = 'custom_pricing_unit' | 'monetary' | OtherString;
+            interface CustomPricingUnit {
+                /**
+                 * The custom pricing unit object.
+                 */
+                custom_pricing_unit_details: CustomPricingUnit.CustomPricingUnitDetails | null;
+                /**
+                 * Unique identifier for the object.
+                 */
+                id: string;
+                /**
+                 * A positive decimal string representing the amount.
+                 */
+                value: Decimal;
+            }
+            interface Monetary {
+                /**
+                 * Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
+                 */
+                currency: string;
+                /**
+                 * A positive integer representing the amount.
+                 */
+                value: number;
+            }
+            namespace CustomPricingUnit {
+                interface CustomPricingUnitDetails {
+                    /**
+                     * Time at which the object was created. Measured in seconds since the Unix epoch.
+                     */
+                    created: number;
+                    /**
+                     * The name of the custom pricing unit.
+                     */
+                    display_name: string;
+                    /**
+                     * Unique identifier for the object.
+                     */
+                    id: string;
+                    /**
+                     * A lookup key for the custom pricing unit.
+                     */
+                    lookup_key: string | null;
+                    /**
+                     * Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
+                     */
+                    metadata: Metadata;
+                    /**
+                     * The status of the custom pricing unit.
+                     */
+                    status: string;
+                }
+            }
+        }
+    }
+    namespace SpendThreshold {
+        interface Filters {
+            /**
+             * Filter by billing cadence ID.
+             */
+            billing_cadence: string | null;
+            /**
+             * Filter by pricing plan ID.
+             */
+            pricing_plan: string | null;
+            /**
+             * Filter by pricing plan subscription ID.
+             */
+            pricing_plan_subscription: string | null;
+        }
+        type GroupBy = 'billing_cadence' | 'pricing_plan_subscription' | OtherString;
+        interface Gte {
+            /**
+             * The monetary amount. Present when type is `amount`.
+             */
+            amount: Gte.Amount | null;
+            /**
+             * The custom pricing unit amount. Present when type is `custom_pricing_unit`.
+             */
+            custom_pricing_unit: Gte.CustomPricingUnit | null;
+            /**
+             * The type of the threshold amount.
+             */
+            type: Gte.Type;
+        }
+        namespace Gte {
+            interface Amount {
+                /**
+                 * Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
+                 */
+                currency: string;
+                /**
+                 * A positive integer representing the amount.
+                 */
+                value: number;
+            }
+            interface CustomPricingUnit {
+                /**
+                 * The custom pricing unit object.
+                 */
+                custom_pricing_unit_details: CustomPricingUnit.CustomPricingUnitDetails | null;
+                /**
+                 * Unique identifier for the object.
+                 */
+                id: string;
+                /**
+                 * A positive decimal string representing the amount.
+                 */
+                value: Decimal;
+            }
+            type Type = 'amount' | 'custom_pricing_unit' | OtherString;
+            namespace CustomPricingUnit {
+                interface CustomPricingUnitDetails {
+                    /**
+                     * Time at which the object was created. Measured in seconds since the Unix epoch.
+                     */
+                    created: number;
+                    /**
+                     * The name of the custom pricing unit.
+                     */
+                    display_name: string;
+                    /**
+                     * Unique identifier for the object.
+                     */
+                    id: string;
+                    /**
+                     * A lookup key for the custom pricing unit.
+                     */
+                    lookup_key: string | null;
+                    /**
+                     * Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
+                     */
+                    metadata: Metadata;
+                    /**
+                     * The status of the custom pricing unit.
+                     */
+                    status: string;
+                }
+            }
+        }
+    }
     namespace UsageThreshold {
         interface Filter {
             /**
@@ -94,21 +300,58 @@ export declare namespace Billing {
         /**
          * The type of alert to create.
          */
-        alert_type: 'usage_threshold';
+        alert_type: AlertCreateParams.AlertType;
         /**
          * The title of the alert.
          */
         title: string;
+        /**
+         * The configuration of the credit balance threshold.
+         */
+        credit_balance_threshold?: AlertCreateParams.CreditBalanceThreshold;
         /**
          * Specifies which fields in the response should be expanded.
          */
         expand?: Array<string>;
+        /**
+         * The configuration of the spend threshold. An event fires when the amount consumed exceeds the threshold, after all credits and discounts are applied but before tax is applied.
+         */
+        spend_threshold?: AlertCreateParams.SpendThreshold;
         /**
          * The configuration of the usage threshold.
          */
         usage_threshold?: AlertCreateParams.UsageThreshold;
     }
     namespace AlertCreateParams {
+        type AlertType = 'credit_balance_threshold' | 'spend_threshold' | 'usage_threshold' | OtherString;
+        interface CreditBalanceThreshold {
+            /**
+             * The filters allows limiting the scope of this credit balance alert. You must specify a customer filter at this time.
+             */
+            filters?: Array<CreditBalanceThreshold.Filter>;
+            /**
+             * Defines at which value the alert will fire.
+             */
+            lte: CreditBalanceThreshold.Lte;
+        }
+        interface SpendThreshold {
+            /**
+             * Defines the period over which spend is aggregated.
+             */
+            aggregation_period: 'billing';
+            /**
+             * Filters to scope the spend calculation.
+             */
+            filters?: SpendThreshold.Filters;
+            /**
+             * Defines the granularity of spend aggregation. Defaults to `pricing_plan_subscription`.
+             */
+            group_by?: SpendThreshold.GroupBy;
+            /**
+             * Defines at which value the alert will fire.
+             */
+            gte: SpendThreshold.Gte;
+        }
         interface UsageThreshold {
             /**
              * The filters allows limiting the scope of this usage alert. You can only specify up to one filter at this time.
@@ -127,6 +370,164 @@ export declare namespace Billing {
              */
             recurrence: 'one_time';
         }
+        namespace CreditBalanceThreshold {
+            interface Filter {
+                /**
+                 * The credit grants for which to configure the credit balance alert.
+                 */
+                credit_grants?: Filter.CreditGrants;
+                /**
+                 * Limit the scope to this credit balance alert only to this customer.
+                 */
+                customer?: string;
+                /**
+                 * What type of filter is being applied to this credit balance alert.
+                 */
+                type: Filter.Type;
+            }
+            interface Lte {
+                /**
+                 * Specify the type of this balance. We currently only support `monetary` billing credits.
+                 */
+                balance_type: Lte.BalanceType;
+                /**
+                 * The custom pricing unit amount.
+                 */
+                custom_pricing_unit?: Lte.CustomPricingUnit;
+                /**
+                 * The monetary amount.
+                 */
+                monetary?: Lte.Monetary;
+            }
+            namespace Filter {
+                interface CreditGrants {
+                    /**
+                     * The applicability configuration for this credit grants filter.
+                     */
+                    applicability_config: CreditGrants.ApplicabilityConfig;
+                }
+                type Type = 'customer' | 'tenant' | OtherString;
+                namespace CreditGrants {
+                    interface ApplicabilityConfig {
+                        /**
+                         * Specify the scope of this applicability config.
+                         */
+                        scope: ApplicabilityConfig.Scope;
+                    }
+                    namespace ApplicabilityConfig {
+                        interface Scope {
+                            /**
+                             * A list of billable items that the credit grant can apply to. We currently only support metered billable items. Cannot be used in combination with `price_type` or `prices`.
+                             */
+                            billable_items?: Array<Scope.BillableItem>;
+                            /**
+                             * The price type that credit grants can apply to. We currently only support the `metered` price type. Cannot be used in combination with `prices`.
+                             */
+                            price_type?: 'metered';
+                            /**
+                             * A list of prices that the credit grant can apply to. We currently only support the `metered` prices. Cannot be used in combination with `price_type`.
+                             */
+                            prices?: Array<Scope.Price>;
+                        }
+                        namespace Scope {
+                            interface BillableItem {
+                                /**
+                                 * The billable item ID this credit grant should apply to.
+                                 */
+                                id: string;
+                            }
+                            interface Price {
+                                /**
+                                 * The price ID this credit grant should apply to.
+                                 */
+                                id: string;
+                            }
+                        }
+                    }
+                }
+            }
+            namespace Lte {
+                type BalanceType = 'custom_pricing_unit' | 'monetary' | OtherString;
+                interface CustomPricingUnit {
+                    /**
+                     * The ID of the custom pricing unit.
+                     */
+                    id: string;
+                    /**
+                     * A positive decimal string representing the amount of the custom pricing unit threshold.
+                     */
+                    value: Decimal;
+                }
+                interface Monetary {
+                    /**
+                     * Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) of the `value` parameter.
+                     */
+                    currency: string;
+                    /**
+                     * An integer representing the amount of the threshold.
+                     */
+                    value: number;
+                }
+            }
+        }
+        namespace SpendThreshold {
+            interface Filters {
+                /**
+                 * Filter by billable item IDs. Maximum of 20 billable items.
+                 */
+                billable_items?: Array<string>;
+                /**
+                 * Filter by billing cadence ID.
+                 */
+                billing_cadence?: string;
+                /**
+                 * Filter by pricing plan ID.
+                 */
+                pricing_plan?: string;
+                /**
+                 * Filter by pricing plan subscription ID.
+                 */
+                pricing_plan_subscription?: string;
+            }
+            type GroupBy = 'billing_cadence' | 'pricing_plan_subscription' | OtherString;
+            interface Gte {
+                /**
+                 * The monetary amount. Required when type is `amount`. The threshold is the total_before_tax, the amount consumed after all credits and discounts are applied, but before tax is applied.
+                 */
+                amount?: Gte.Amount;
+                /**
+                 * The custom pricing unit amount. Required when type is `custom_pricing_unit`.
+                 */
+                custom_pricing_unit?: Gte.CustomPricingUnit;
+                /**
+                 * The type of the threshold amount.
+                 */
+                type: Gte.Type;
+            }
+            namespace Gte {
+                interface Amount {
+                    /**
+                     * Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) of the `value` parameter.
+                     */
+                    currency: string;
+                    /**
+                     * An integer representing the amount of the threshold.
+                     */
+                    value: number;
+                }
+                interface CustomPricingUnit {
+                    /**
+                     * The ID of the custom pricing unit.
+                     */
+                    id: string;
+                    /**
+                     * A positive decimal string representing the amount of the custom pricing unit threshold.
+                     */
+                    value: Decimal;
+                }
+                type Type = 'amount' | 'custom_pricing_unit' | OtherString;
+            }
+        }
         namespace UsageThreshold {
             interface Filter {
                 /**
@@ -154,7 +555,11 @@ export declare namespace Billing {
         /**
          * Filter results to only include this type of alert.
          */
-        alert_type?: 'usage_threshold';
+        alert_type?: AlertListParams.AlertType;
+        /**
+         * Filter results to only include alerts for the given customer.
+         */
+        customer?: string;
         /**
          * Specifies which fields in the response should be expanded.
          */
@@ -164,6 +569,9 @@ export declare namespace Billing {
          */
         meter?: string;
     }
+    namespace AlertListParams {
+        type AlertType = 'credit_balance_threshold' | 'spend_threshold' | 'usage_threshold' | OtherString;
+    }
 }
 export declare namespace Billing {
     interface AlertActivateParams {
@@ -189,3 +597,38 @@ export declare namespace Billing {
         expand?: Array<string>;
     }
 }
+export declare namespace Billing {
+    interface AlertListNotificationsParams extends PaginationParams {
+        /**
+         * The customer to list notifications for.
+         */
+        customer: string;
+        /**
+         * Filter results to only include triggered or recovered notifications.
+         */
+        action?: AlertListNotificationsParams.Action;
+        /**
+         * Filter results to only include notifications for the given billing cadence.
+         */
+        cadence?: string;
+        /**
+         * Specifies which fields in the response should be expanded.
+         */
+        expand?: Array<string>;
+        /**
+         * Filter results to only include notifications for the given meter.
+         */
+        meter?: string;
+        /**
+         * Filter results according to when the notification was sent.
+         */
+        notified_at?: RangeQueryParam | number;
+        /**
+         * Filter results to only include notifications for the given subscription.
+         */
+        subscription?: string;
+    }
+    namespace AlertListNotificationsParams {
+        type Action = 'recovered' | 'triggered';
+    }
+}