stripe 22.2.0 → 22.3.0-alpha.2

package/esm/resources/Billing/AlertTriggereds.d.ts

@@ -1,9 +1,14 @@
 import { Alert } from './Alerts.js';
+import { Decimal } from '../../shared.js';
 export interface AlertTriggered {
     /**
      * String representing the object's type. Objects of the same type share the same value.
      */
     object: 'billing.alert_triggered';
+    /**
+     * The aggregation period for which this alert triggered
+     */
+    aggregation_period?: Billing.AlertTriggered.AggregationPeriod | null;
     /**
      * A billing alert is a resource that notifies you when a certain usage threshold on a meter is crossed. For example, you might create a billing alert to notify you when a certain user made 100 API requests.
      */
@@ -12,16 +17,67 @@ export interface AlertTriggered {
      * Time at which the object was created. Measured in seconds since the Unix epoch.
      */
     created: number;
+    /**
+     * Currency for the threshold value
+     */
+    currency?: string | null;
+    /**
+     * Custom pricing unit for the threshold value
+     */
+    custom_pricing_unit?: string | null;
     /**
      * ID of customer for which the alert triggered
      */
     customer: string;
+    /**
+     * External customer ID for the customer for which the alert triggered
+     */
+    external_customer_id?: string | null;
+    /**
+     * Populated specifically for spend alerts to notify merchants which group_by entity has the exceeded spend
+     */
+    group_by?: Billing.AlertTriggered.GroupBy | 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;
+    /**
+     * Timestamp at which the threshold was crossed
+     */
+    triggered_at?: number | null;
     /**
      * The value triggering the alert
      */
-    value: number;
+    value: Decimal;
+}
+export declare namespace Billing {
+    namespace AlertTriggered {
+        interface AggregationPeriod {
+            /**
+             * End time of the aggregation period
+             */
+            ends_at: number;
+            /**
+             * Start time of the aggregation period
+             */
+            starts_at: number;
+        }
+        interface GroupBy {
+            /**
+             * The billing cadence ID, populated when type is `billing_cadence`
+             */
+            billing_cadence: string | null;
+            /**
+             * The pricing plan subscription ID, populated when type is `pricing_plan_subscription`
+             */
+            pricing_plan_subscription: string | null;
+            /**
+             * The type of grouping used for this alert notification
+             */
+            type: GroupBy.Type;
+        }
+        namespace GroupBy {
+            type Type = 'billing_cadence' | 'pricing_plan_subscription';
+        }
+    }
 }

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

@@ -1,7 +1,7 @@
 import { StripeResource } from '../../StripeResource.js';
-import { Meter } from './Meters.js';
 import { Customer } from './../Customers.js';
-import { PaginationParams } from '../../shared.js';
+import { Meter } from './Meters.js';
+import { Decimal, PaginationParams, Metadata } from '../../shared.js';
 import { RequestOptions, ApiListPromise, Response } from '../../lib.js';
 export declare class AlertResource extends StripeResource {
     /**
@@ -41,11 +41,19 @@ export interface Alert {
     /**
      * Defines the type of the alert.
      */
-    alert_type: 'usage_threshold';
+    alert_type: Billing.Alert.AlertType;
+    /**
+     * Encapsulates configuration of the alert to monitor billing credit balance.
+     */
+    credit_balance_threshold?: Billing.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?: Billing.Alert.SpendThreshold | null;
     /**
      * Status of the alert. This can be active, inactive or archived.
      */
@@ -61,6 +69,32 @@ export interface Alert {
 }
 export declare namespace Billing {
     namespace Alert {
+        type AlertType = 'credit_balance_threshold' | 'spend_threshold' | 'usage_threshold';
+        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';
         interface UsageThreshold {
             /**
@@ -80,6 +114,173 @@ export declare namespace Billing {
              */
             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';
+            }
+            namespace Lte {
+                type BalanceType = 'custom_pricing_unit' | 'monetary';
+                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';
+            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';
+                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 {
                 /**
@@ -96,21 +297,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';
+        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.
@@ -129,6 +367,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';
+                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';
+                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';
+            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';
+            }
+        }
         namespace UsageThreshold {
             interface Filter {
                 /**
@@ -156,7 +552,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.
          */
@@ -166,6 +566,9 @@ export declare namespace Billing {
          */
         meter?: string;
     }
+    namespace AlertListParams {
+        type AlertType = 'credit_balance_threshold' | 'spend_threshold' | 'usage_threshold';
+    }
 }
 export declare namespace Billing {
     interface AlertActivateParams {