stripe 20.1.0-alpha.4 → 20.1.0

package/types/Subscriptions.d.ts

@@ -5,7 +5,7 @@ declare module 'stripe' {
     /**
      * Subscriptions allow you to charge a customer on a recurring basis.
      *
-     * Related guide: [Creating subscriptions](https://stripe.com/docs/billing/subscriptions/creating)
+     * Related guide: [Creating subscriptions](https://docs.stripe.com/billing/subscriptions/creating)
      */
     interface Subscription {
       /**
@@ -35,12 +35,7 @@ declare module 'stripe' {
       automatic_tax: Subscription.AutomaticTax;
 
       /**
-       * The Billing Cadence which controls the timing of recurring invoice generation for this subscription.If unset, the subscription will bill according to its own configured schedule and create its own invoices.If set, this subscription will be billed by the cadence instead, potentially sharing invoices with the other subscriptions linked to that Cadence.
-       */
-      billing_cadence?: string;
-
-      /**
-       * The reference point that aligns future [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle) dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals. The timestamp is in UTC format.
+       * The reference point that aligns future [billing cycle](https://docs.stripe.com/subscriptions/billing-cycle) dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals. The timestamp is in UTC format.
        */
       billing_cycle_anchor: number;
 
@@ -54,11 +49,6 @@ declare module 'stripe' {
        */
       billing_mode: Subscription.BillingMode;
 
-      /**
-       * Billing schedules for this subscription.
-       */
-      billing_schedules?: Array<Subscription.BillingSchedule>;
-
       /**
        * Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period
        */
@@ -105,9 +95,9 @@ declare module 'stripe' {
       customer: string | Stripe.Customer | Stripe.DeletedCustomer;
 
       /**
-       * ID of the account who owns the subscription.
+       * ID of the account representing the customer who owns the subscription.
        */
-      customer_account?: string | null;
+      customer_account: string | null;
 
       /**
        * Number of days a customer has to pay invoices generated by this subscription. This value will be `null` for subscriptions where `collection_method=charge_automatically`.
@@ -115,12 +105,12 @@ declare module 'stripe' {
       days_until_due: number | null;
 
       /**
-       * ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
+       * ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
        */
       default_payment_method: string | Stripe.PaymentMethod | null;
 
       /**
-       * ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source).
+       * ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source).
        */
       default_source: string | Stripe.CustomerSource | null;
 
@@ -151,11 +141,6 @@ declare module 'stripe' {
        */
       items: ApiList<Stripe.SubscriptionItem>;
 
-      /**
-       * Details of the most recent price migration that failed for the subscription.
-       */
-      last_price_migration_error?: Subscription.LastPriceMigrationError | null;
-
       /**
        * The most recent invoice this subscription has generated.
        */
@@ -167,7 +152,7 @@ declare module 'stripe' {
       livemode: boolean;
 
       /**
-       * Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
+       * 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: Stripe.Metadata;
 
@@ -177,12 +162,12 @@ declare module 'stripe' {
       next_pending_invoice_item_invoice: number | null;
 
       /**
-       * The account (if any) the charge was made on behalf of for charges associated with this subscription. See the [Connect documentation](https://stripe.com/docs/connect/subscriptions#on-behalf-of) for details.
+       * The account (if any) the charge was made on behalf of for charges associated with this subscription. See the [Connect documentation](https://docs.stripe.com/connect/subscriptions#on-behalf-of) for details.
        */
       on_behalf_of: string | Stripe.Account | null;
 
       /**
-       * If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to `paused`. Learn more about [pausing collection](https://stripe.com/docs/billing/subscriptions/pause-payment).
+       * If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to `paused`. Learn more about [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment).
        */
       pause_collection: Subscription.PauseCollection | null;
 
@@ -192,25 +177,20 @@ declare module 'stripe' {
       payment_settings: Subscription.PaymentSettings | null;
 
       /**
-       * Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](https://stripe.com/docs/api#create_invoice) for the given subscription at the specified interval.
+       * Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](https://docs.stripe.com/api#create_invoice) for the given subscription at the specified interval.
        */
       pending_invoice_item_interval: Subscription.PendingInvoiceItemInterval | null;
 
       /**
-       * You can use this [SetupIntent](https://stripe.com/docs/api/setup_intents) to collect user authentication when creating a subscription without immediate payment or updating a subscription's payment method, allowing you to optimize for off-session payments. Learn more in the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication#scenario-2).
+       * You can use this [SetupIntent](https://docs.stripe.com/api/setup_intents) to collect user authentication when creating a subscription without immediate payment or updating a subscription's payment method, allowing you to optimize for off-session payments. Learn more in the [SCA Migration Guide](https://docs.stripe.com/billing/migration/strong-customer-authentication#scenario-2).
        */
       pending_setup_intent: string | Stripe.SetupIntent | null;
 
       /**
-       * If specified, [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates) that will be applied to the subscription once the `latest_invoice` has been paid.
+       * If specified, [pending updates](https://docs.stripe.com/billing/subscriptions/pending-updates) that will be applied to the subscription once the `latest_invoice` has been paid.
        */
       pending_update: Subscription.PendingUpdate | null;
 
-      /**
-       * Time period and invoice for a Subscription billed in advance.
-       */
-      prebilling?: Subscription.Prebilling | null;
-
       /**
        * The schedule attached to the subscription
        */
@@ -228,7 +208,7 @@ declare module 'stripe' {
        *
        * A subscription that is currently in a trial period is `trialing` and moves to `active` when the trial period is over.
        *
-       * A subscription can only enter a `paused` status [when a trial ends without a payment method](https://stripe.com/docs/billing/subscriptions/trials#create-free-trials-without-payment). A `paused` subscription doesn't generate invoices and can be resumed after your customer adds their payment method. The `paused` status is different from [pausing collection](https://stripe.com/docs/billing/subscriptions/pause-payment), which still generates invoices and leaves the subscription's status unchanged.
+       * A subscription can only enter a `paused` status [when a trial ends without a payment method](https://docs.stripe.com/billing/subscriptions/trials#create-free-trials-without-payment). A `paused` subscription doesn't generate invoices and can be resumed after your customer adds their payment method. The `paused` status is different from [pausing collection](https://docs.stripe.com/billing/subscriptions/pause-payment), which still generates invoices and leaves the subscription's status unchanged.
        *
        * If subscription `collection_method=charge_automatically`, it becomes `past_due` when payment is required but cannot be paid (due to failed payment or awaiting additional user actions). Once Stripe has exhausted all payment retry attempts, the subscription will become `canceled` or `unpaid` (depending on your subscriptions settings).
        *
@@ -357,101 +337,6 @@ declare module 'stripe' {
         type Type = 'classic' | 'flexible';
       }
 
-      interface BillingSchedule {
-        /**
-         * Specifies which subscription items the billing schedule applies to.
-         */
-        applies_to: Array<BillingSchedule.AppliesTo> | null;
-
-        /**
-         * Specifies the start of the billing period.
-         */
-        bill_from?: BillingSchedule.BillFrom | null;
-
-        /**
-         * Specifies the end of billing period.
-         */
-        bill_until: BillingSchedule.BillUntil;
-
-        /**
-         * Unique identifier for the billing schedule.
-         */
-        key: string;
-      }
-
-      namespace BillingSchedule {
-        interface AppliesTo {
-          /**
-           * The billing schedule will apply to the subscription item with the given price ID.
-           */
-          price: string | Stripe.Price | null;
-
-          /**
-           * Controls which subscription items the billing schedule applies to.
-           */
-          type: 'price';
-        }
-
-        interface BillFrom {
-          /**
-           * The time the billing schedule applies from.
-           */
-          computed_timestamp: number;
-
-          /**
-           * Use a precise Unix timestamp for prebilling to start. Must be earlier than `bill_until`.
-           */
-          timestamp: number | null;
-
-          /**
-           * Describes how the billing schedule determines the start date. Possible values are `timestamp`.
-           */
-          type: 'timestamp';
-        }
-
-        interface BillUntil {
-          /**
-           * The timestamp the billing schedule will apply until.
-           */
-          computed_timestamp: number;
-
-          /**
-           * Specifies the billing period.
-           */
-          duration: BillUntil.Duration | null;
-
-          /**
-           * If specified, the billing schedule will apply until the specified timestamp.
-           */
-          timestamp: number | null;
-
-          /**
-           * Describes how the billing schedule will determine the end date. Either `duration` or `timestamp`.
-           */
-          type: BillUntil.Type;
-        }
-
-        namespace BillUntil {
-          interface Duration {
-            /**
-             * Specifies billing duration. Either `day`, `week`, `month` or `year`.
-             */
-            interval: Duration.Interval;
-
-            /**
-             * The multiplier applied to the interval.
-             */
-            interval_count: number | null;
-          }
-
-          namespace Duration {
-            type Interval = 'day' | 'month' | 'week' | 'year';
-          }
-
-          type Type = 'duration' | 'timestamp';
-        }
-      }
-
       interface BillingThresholds {
         /**
          * Monetary threshold that triggers the subscription to create an invoice
@@ -529,37 +414,6 @@ declare module 'stripe' {
         }
       }
 
-      interface LastPriceMigrationError {
-        /**
-         * The time at which the price migration encountered an error.
-         */
-        errored_at: number;
-
-        /**
-         * The involved price pairs in each failed transition.
-         */
-        failed_transitions: Array<LastPriceMigrationError.FailedTransition>;
-
-        /**
-         * The type of error encountered by the price migration.
-         */
-        type: 'price_uniqueness_violation';
-      }
-
-      namespace LastPriceMigrationError {
-        interface FailedTransition {
-          /**
-           * The original price to be migrated.
-           */
-          source_price: string;
-
-          /**
-           * The intended resulting price of the migration.
-           */
-          target_price: string;
-        }
-      }
-
       interface PauseCollection {
         /**
          * The payment collection behavior for this subscription while paused. One of `keep_as_draft`, `mark_uncollectible`, or `void`.
@@ -615,31 +469,21 @@ declare module 'stripe' {
            */
           customer_balance: PaymentMethodOptions.CustomerBalance | null;
 
-          /**
-           * This sub-hash contains details about the Indonesia bank transfer payment method options to pass to invoices created by the subscription.
-           */
-          id_bank_transfer?: PaymentMethodOptions.IdBankTransfer | null;
-
           /**
            * This sub-hash contains details about the Konbini payment method options to pass to invoices created by the subscription.
            */
           konbini: PaymentMethodOptions.Konbini | null;
 
           /**
-           * This sub-hash contains details about the Pix payment method options to pass to invoices created by the subscription.
+           * This sub-hash contains details about the PayTo payment method options to pass to invoices created by the subscription.
            */
-          pix?: PaymentMethodOptions.Pix | null;
+          payto?: PaymentMethodOptions.Payto | null;
 
           /**
            * This sub-hash contains details about the SEPA Direct Debit payment method options to pass to invoices created by the subscription.
            */
           sepa_debit: PaymentMethodOptions.SepaDebit | null;
 
-          /**
-           * This sub-hash contains details about the UPI payment method options to pass to invoices created by the subscription.
-           */
-          upi?: PaymentMethodOptions.Upi | null;
-
           /**
            * This sub-hash contains details about the ACH direct debit payment method options to pass to invoices created by the subscription.
            */
@@ -691,7 +535,7 @@ declare module 'stripe' {
             network: Card.Network | null;
 
             /**
-             * We strongly recommend that you rely on our SCA Engine to automatically prompt your customers for authentication based on risk level and [other requirements](https://stripe.com/docs/strong-customer-authentication). However, if you wish to request 3D Secure based on logic from your own fraud engine, provide this option. Read our guide on [manually requesting 3D Secure](https://stripe.com/docs/payments/3d-secure/authentication-flow#manual-three-ds) for more information on how this configuration interacts with Radar and our SCA Engine.
+             * We strongly recommend that you rely on our SCA Engine to automatically prompt your customers for authentication based on risk level and [other requirements](https://docs.stripe.com/strong-customer-authentication). However, if you wish to request 3D Secure based on logic from your own fraud engine, provide this option. Read our guide on [manually requesting 3D Secure](https://docs.stripe.com/payments/3d-secure/authentication-flow#manual-three-ds) for more information on how this configuration interacts with Radar and our SCA Engine.
              */
             request_three_d_secure: Card.RequestThreeDSecure | null;
           }
@@ -769,83 +613,50 @@ declare module 'stripe' {
             }
           }
 
-          interface IdBankTransfer {}
-
           interface Konbini {}
 
-          interface Pix {
-            mandate_options?: Pix.MandateOptions;
+          interface Payto {
+            mandate_options?: Payto.MandateOptions;
           }
 
-          namespace Pix {
+          namespace Payto {
             interface MandateOptions {
               /**
-               * Amount to be charged for future payments.
+               * The maximum amount that can be collected in a single invoice. If you don't specify a maximum, then there is no limit.
                */
               amount: number | null;
 
               /**
-               * Determines if the amount includes the IOF tax.
-               */
-              amount_includes_iof: MandateOptions.AmountIncludesIof | null;
-
-              /**
-               * Date when the mandate expires and no further payments will be charged, in `YYYY-MM-DD`.
-               */
-              end_date: string | null;
-
-              /**
-               * Schedule at which the future payments will be charged.
-               */
-              payment_schedule: MandateOptions.PaymentSchedule | null;
-            }
-
-            namespace MandateOptions {
-              type AmountIncludesIof = 'always' | 'never';
-
-              type PaymentSchedule =
-                | 'halfyearly'
-                | 'monthly'
-                | 'quarterly'
-                | 'weekly'
-                | 'yearly';
-            }
-          }
-
-          interface SepaDebit {}
-
-          interface Upi {
-            mandate_options?: Upi.MandateOptions;
-          }
-
-          namespace Upi {
-            interface MandateOptions {
-              /**
-               * Amount to be charged for future payments.
-               */
-              amount: number | null;
-
-              /**
-               * One of `fixed` or `maximum`. If `fixed`, the `amount` param refers to the exact amount to be charged in future payments. If `maximum`, the amount charged can be up to the value passed for the `amount` param.
+               * Only `maximum` is supported.
                */
               amount_type: MandateOptions.AmountType | null;
 
               /**
-               * A description of the mandate or subscription that is meant to be displayed to the customer.
-               */
-              description: string | null;
-
-              /**
-               * End date of the mandate or subscription. If not provided, the mandate will be active until canceled. If provided, end date should be after start date.
+               * The purpose for which payments are made. Has a default value based on your merchant category code.
                */
-              end_date: number | null;
+              purpose: MandateOptions.Purpose | null;
             }
 
             namespace MandateOptions {
               type AmountType = 'fixed' | 'maximum';
+
+              type Purpose =
+                | 'dependant_support'
+                | 'government'
+                | 'loan'
+                | 'mortgage'
+                | 'other'
+                | 'pension'
+                | 'personal'
+                | 'retail'
+                | 'salary'
+                | 'tax'
+                | 'utility';
             }
           }
 
+          interface SepaDebit {}
+
           interface UsBankAccount {
             financial_connections?: UsBankAccount.FinancialConnections;
 
@@ -876,11 +687,6 @@ declare module 'stripe' {
                  * The account subcategories to use to filter for possible accounts to link. Valid subcategories are `checking` and `savings`.
                  */
                 account_subcategories?: Array<Filters.AccountSubcategory>;
-
-                /**
-                 * The institution to use to filter for possible accounts to link.
-                 */
-                institution?: string;
               }
 
               namespace Filters {
@@ -893,11 +699,7 @@ declare module 'stripe' {
                 | 'payment_method'
                 | 'transactions';
 
-              type Prefetch =
-                | 'balances'
-                | 'inferred_balances'
-                | 'ownership'
-                | 'transactions';
+              type Prefetch = 'balances' | 'ownership' | 'transactions';
             }
 
             type VerificationMethod = 'automatic' | 'instant' | 'microdeposits';
@@ -923,7 +725,6 @@ declare module 'stripe' {
           | 'fpx'
           | 'giropay'
           | 'grabpay'
-          | 'id_bank_transfer'
           | 'ideal'
           | 'jp_credit_transfer'
           | 'kakao_pay'
@@ -938,15 +739,13 @@ declare module 'stripe' {
           | 'payco'
           | 'paynow'
           | 'paypal'
-          | 'pix'
+          | 'payto'
           | 'promptpay'
           | 'revolut_pay'
           | 'sepa_credit_transfer'
           | 'sepa_debit'
           | 'sofort'
-          | 'stripe_balance'
           | 'swish'
-          | 'upi'
           | 'us_bank_account'
           | 'wechat_pay';
 
@@ -980,11 +779,6 @@ declare module 'stripe' {
          */
         expires_at: number;
 
-        /**
-         * The number of iterations of prebilling to apply.
-         */
-        prebilling_iterations?: number | null;
-
         /**
          * List of subscription items, each with an attached plan, that will be set if the update is applied.
          */
@@ -996,37 +790,11 @@ declare module 'stripe' {
         trial_end: number | null;
 
         /**
-         * Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more.
+         * Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://docs.stripe.com/billing/subscriptions/trials) to learn more.
          */
         trial_from_plan: boolean | null;
       }
 
-      interface Prebilling {
-        /**
-         * ID of the prebilling invoice.
-         */
-        invoice: string | Stripe.Invoice;
-
-        /**
-         * The end of the last period for which the invoice pre-bills.
-         */
-        period_end: number;
-
-        /**
-         * The start of the first period for which the invoice pre-bills.
-         */
-        period_start: number;
-
-        /**
-         * Whether to cancel or preserve `prebilling` if the subscription is updated during the prebilled period.
-         */
-        update_behavior?: Prebilling.UpdateBehavior;
-      }
-
-      namespace Prebilling {
-        type UpdateBehavior = 'prebill' | 'reset';
-      }
-
       type Status =
         | 'active'
         | 'canceled'