stripe 19.3.1 → 19.4.0-alpha.2

package/types/SubscriptionSchedules.d.ts

@@ -27,11 +27,21 @@ declare module 'stripe' {
         | Stripe.DeletedApplication
         | null;
 
+      /**
+       * Configures when the subscription schedule generates prorations for phase transitions. Possible values are `prorate_on_next_phase` or `prorate_up_front` with the default being `prorate_on_next_phase`. `prorate_on_next_phase` will apply phase changes and generate prorations at transition time. `prorate_up_front` will bill for all phases within the current billing cycle up front.
+       */
+      billing_behavior?: SubscriptionSchedule.BillingBehavior;
+
       /**
        * The billing mode of the subscription.
        */
       billing_mode: SubscriptionSchedule.BillingMode;
 
+      /**
+       * Billing schedules for this subscription schedule.
+       */
+      billing_schedules?: Array<SubscriptionSchedule.BillingSchedule> | null;
+
       /**
        * Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch.
        */
@@ -57,6 +67,11 @@ declare module 'stripe' {
        */
       customer: string | Stripe.Customer | Stripe.DeletedCustomer;
 
+      /**
+       * ID of the account who owns the subscription schedule.
+       */
+      customer_account?: string | null;
+
       default_settings: SubscriptionSchedule.DefaultSettings;
 
       /**
@@ -64,6 +79,16 @@ declare module 'stripe' {
        */
       end_behavior: SubscriptionSchedule.EndBehavior;
 
+      /**
+       * Details of the most recent price migration that failed for the subscription schedule.
+       */
+      last_price_migration_error?: SubscriptionSchedule.LastPriceMigrationError | null;
+
+      /**
+       * The most recent invoice this subscription schedule has generated.
+       */
+      latest_invoice?: string | Stripe.Invoice | null;
+
       /**
        * Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
        */
@@ -79,6 +104,11 @@ declare module 'stripe' {
        */
       phases: Array<SubscriptionSchedule.Phase>;
 
+      /**
+       * Time period and invoice for a Subscription billed in advance.
+       */
+      prebilling?: SubscriptionSchedule.Prebilling | null;
+
       /**
        * Time at which the subscription schedule was released. Measured in seconds since the Unix epoch.
        */
@@ -106,6 +136,8 @@ declare module 'stripe' {
     }
 
     namespace SubscriptionSchedule {
+      type BillingBehavior = 'prorate_on_next_phase' | 'prorate_up_front';
+
       interface BillingMode {
         /**
          * Configure behavior for flexible billing mode
@@ -138,6 +170,187 @@ 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 billing period.
+         */
+        bill_until: BillingSchedule.BillUntil;
+
+        /**
+         * Unique identifier for the billing schedule.
+         */
+        key: string;
+
+        /**
+         * Specifies the start of the billing period.
+         */
+        bill_from?: BillingSchedule.BillFrom | null;
+      }
+
+      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 {
+          /**
+           * Use an index to specify the position of an amendment to start prebilling with.
+           */
+          amendment_start: BillFrom.AmendmentStart | null;
+
+          /**
+           * The time the billing schedule applies from.
+           */
+          computed_timestamp: number | null;
+
+          /**
+           * Lets you bill the period starting from a particular Quote line.
+           */
+          line_starts_at: BillFrom.LineStartsAt | null;
+
+          /**
+           * Timestamp is calculated from the request time.
+           */
+          relative: BillFrom.Relative | null;
+
+          /**
+           * 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`, `relative`, `amendment_start`, `now`, `quote_acceptance_date`, `line_starts_at`, or `pause_collection_start`.
+           */
+          type: BillFrom.Type;
+        }
+
+        namespace BillFrom {
+          interface AmendmentStart {
+            /**
+             * Use an index to specify the position of an amendment to start prebilling with.
+             */
+            index: number;
+          }
+
+          interface LineStartsAt {
+            /**
+             * Unique identifier for the object.
+             */
+            id: string;
+          }
+
+          interface Relative {
+            /**
+             * Specifies billing duration. Possible values are `day`, `week`, `month`, or `year`.
+             */
+            interval: Relative.Interval;
+
+            /**
+             * The multiplier applied to the interval.
+             */
+            interval_count: number | null;
+          }
+
+          namespace Relative {
+            type Interval = 'day' | 'month' | 'week' | 'year';
+          }
+
+          type Type =
+            | 'amendment_start'
+            | 'line_starts_at'
+            | 'now'
+            | 'pause_collection_start'
+            | 'quote_acceptance_date'
+            | 'relative'
+            | '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;
+
+          /**
+           * Use an index to specify the position of an amendment to end prebilling with.
+           */
+          amendment_end?: BillUntil.AmendmentEnd | null;
+
+          /**
+           * Lets you bill the period ending at a particular Quote line.
+           */
+          line_ends_at?: BillUntil.LineEndsAt | null;
+        }
+
+        namespace BillUntil {
+          interface AmendmentEnd {
+            /**
+             * Use an index to specify the position of an amendment to end prebilling with.
+             */
+            index: number;
+          }
+
+          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';
+          }
+
+          interface LineEndsAt {
+            /**
+             * Unique identifier for the object.
+             */
+            id: string;
+          }
+
+          type Type =
+            | 'amendment_end'
+            | 'duration'
+            | 'line_ends_at'
+            | 'schedule_end'
+            | 'timestamp'
+            | 'upcoming_invoice';
+        }
+      }
+
       interface CurrentPhase {
         /**
          * The end of this phase of the subscription schedule.
@@ -194,6 +407,11 @@ declare module 'stripe' {
          * The account (if any) the associated subscription's payments will be attributed to for tax reporting, and where funds from each payment will be transferred to for each of the subscription's invoices.
          */
         transfer_data: DefaultSettings.TransferData | null;
+
+        /**
+         * Configures how the subscription schedule handles billing for phase transitions. Possible values are `phase_start` (default) or `billing_period_start`. `phase_start` bills based on the current state of the subscription, ignoring changes scheduled in future phases. `billing_period_start` bills predictively for upcoming phase transitions within the current billing cycle, including pricing changes and service period adjustments that will occur before the next invoice.
+         */
+        phase_effective_at?: DefaultSettings.PhaseEffectiveAt | null;
       }
 
       namespace DefaultSettings {
@@ -282,6 +500,8 @@ declare module 'stripe' {
           }
         }
 
+        type PhaseEffectiveAt = 'billing_period_start' | 'phase_start';
+
         interface TransferData {
           /**
            * A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the destination account. By default, the entire amount is transferred to the destination.
@@ -297,6 +517,37 @@ declare module 'stripe' {
 
       type EndBehavior = 'cancel' | 'none' | 'release' | 'renew';
 
+      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 Phase {
         /**
          * A list of prices and quantities that will generate invoice items appended to the next invoice for this phase.
@@ -375,6 +626,11 @@ declare module 'stripe' {
          */
         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).
+         */
+        pause_collection?: Phase.PauseCollection | null;
+
         /**
          * When transitioning phases, controls how prorations are handled (if any). Possible values are `create_prorations`, `none`, and `always_invoice`.
          */
@@ -390,10 +646,20 @@ declare module 'stripe' {
          */
         transfer_data: Phase.TransferData | null;
 
+        /**
+         * Specify behavior of the trial when crossing schedule phase boundaries
+         */
+        trial_continuation?: Phase.TrialContinuation | null;
+
         /**
          * When the trial ends within the phase.
          */
         trial_end: number | null;
+
+        /**
+         * Settings related to any trials on the subscription during this phase.
+         */
+        trial_settings?: Phase.TrialSettings | null;
       }
 
       namespace Phase {
@@ -438,12 +704,31 @@ declare module 'stripe' {
              */
             discount: string | Stripe.Discount | null;
 
+            /**
+             * Details to determine how long the discount should be applied for.
+             */
+            discount_end?: Discount.DiscountEnd | null;
+
             /**
              * ID of the promotion code to create a new discount for.
              */
             promotion_code: string | Stripe.PromotionCode | null;
           }
 
+          namespace Discount {
+            interface DiscountEnd {
+              /**
+               * The discount end timestamp.
+               */
+              timestamp: number | null;
+
+              /**
+               * The discount end type.
+               */
+              type: 'timestamp';
+            }
+          }
+
           interface Period {
             end: Period.End;
 
@@ -547,12 +832,31 @@ declare module 'stripe' {
            */
           discount: string | Stripe.Discount | null;
 
+          /**
+           * Details to determine how long the discount should be applied for.
+           */
+          discount_end?: Discount.DiscountEnd | null;
+
           /**
            * ID of the promotion code to create a new discount for.
            */
           promotion_code: string | Stripe.PromotionCode | null;
         }
 
+        namespace Discount {
+          interface DiscountEnd {
+            /**
+             * The discount end timestamp.
+             */
+            timestamp: number | null;
+
+            /**
+             * The discount end type.
+             */
+            type: 'timestamp';
+          }
+        }
+
         interface InvoiceSettings {
           /**
            * The account tax IDs associated with this phase of the subscription schedule. Will be set on invoices generated by this phase of the subscription schedule.
@@ -625,6 +929,11 @@ declare module 'stripe' {
            * The tax rates which apply to this `phase_item`. When set, the `default_tax_rates` on the phase do not apply to this `phase_item`.
            */
           tax_rates?: Array<Stripe.TaxRate> | null;
+
+          /**
+           * Options that configure the trial on the subscription item.
+           */
+          trial?: Item.Trial | null;
         }
 
         namespace Item {
@@ -646,11 +955,57 @@ declare module 'stripe' {
              */
             discount: string | Stripe.Discount | null;
 
+            /**
+             * Details to determine how long the discount should be applied for.
+             */
+            discount_end?: Discount.DiscountEnd | null;
+
             /**
              * ID of the promotion code to create a new discount for.
              */
             promotion_code: string | Stripe.PromotionCode | null;
           }
+
+          namespace Discount {
+            interface DiscountEnd {
+              /**
+               * The discount end timestamp.
+               */
+              timestamp: number | null;
+
+              /**
+               * The discount end type.
+               */
+              type: 'timestamp';
+            }
+          }
+
+          interface Trial {
+            /**
+             * List of price IDs which, if present on the subscription following a paid trial, constitute opting-in to the paid trial.
+             */
+            converts_to?: Array<string> | null;
+
+            /**
+             * Determines the type of trial for this item.
+             */
+            type: Trial.Type;
+          }
+
+          namespace Trial {
+            type Type = 'free' | 'paid';
+          }
+        }
+
+        interface PauseCollection {
+          /**
+           * The payment collection behavior for this subscription while paused. One of `keep_as_draft`, `mark_uncollectible`, or `void`.
+           */
+          behavior: PauseCollection.Behavior;
+        }
+
+        namespace PauseCollection {
+          type Behavior = 'keep_as_draft' | 'mark_uncollectible' | 'void';
         }
 
         type ProrationBehavior =
@@ -669,6 +1024,54 @@ declare module 'stripe' {
            */
           destination: string | Stripe.Account;
         }
+
+        type TrialContinuation = 'continue' | 'none';
+
+        interface TrialSettings {
+          /**
+           * Defines how the subscription should behave when a trial ends.
+           */
+          end_behavior: TrialSettings.EndBehavior | null;
+        }
+
+        namespace TrialSettings {
+          interface EndBehavior {
+            /**
+             * Configure how an opt-in following a paid trial is billed when using `billing_behavior: prorate_up_front`.
+             */
+            prorate_up_front: EndBehavior.ProrateUpFront | null;
+          }
+
+          namespace EndBehavior {
+            type ProrateUpFront = 'defer' | 'include';
+          }
+        }
+      }
+
+      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 =