From 86101964b19342dc9e914fb670a26bc8a14ec3e9 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 17 Apr 2024 17:27:04 +0000 Subject: [PATCH 1/9] Update generated code for v963 --- OPENAPI_VERSION | 2 +- stripe/_confirmation_token.py | 6 ++++++ stripe/_customer.py | 6 ++++++ stripe/_customer_payment_method_service.py | 6 ++++++ stripe/_payment_intent.py | 18 ++++++++++++++++++ stripe/_payment_intent_service.py | 18 ++++++++++++++++++ stripe/_payment_method.py | 12 ++++++++++++ stripe/_payment_method_service.py | 12 ++++++++++++ stripe/_setup_intent.py | 18 ++++++++++++++++++ stripe/_setup_intent_service.py | 18 ++++++++++++++++++ .../_confirmation_token_service.py | 6 ++++++ 11 files changed, 121 insertions(+), 1 deletion(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index ea2fb0ba1..b158e42fd 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v961 \ No newline at end of file +v963 \ No newline at end of file diff --git a/stripe/_confirmation_token.py b/stripe/_confirmation_token.py index b569a400f..42a2e924f 100644 --- a/stripe/_confirmation_token.py +++ b/stripe/_confirmation_token.py @@ -1224,6 +1224,12 @@ class CreateParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "ConfirmationToken.CreateParamsPaymentMethodDataAmazonPay" ] diff --git a/stripe/_customer.py b/stripe/_customer.py index 0d6f32fcc..f3da232c0 100644 --- a/stripe/_customer.py +++ b/stripe/_customer.py @@ -804,6 +804,12 @@ class ListParamsCreated(TypedDict): """ class ListPaymentMethodsParams(RequestOptions): + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ ending_before: NotRequired[str] """ A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. diff --git a/stripe/_customer_payment_method_service.py b/stripe/_customer_payment_method_service.py index 2391597d0..21a8870d0 100644 --- a/stripe/_customer_payment_method_service.py +++ b/stripe/_customer_payment_method_service.py @@ -11,6 +11,12 @@ class CustomerPaymentMethodService(StripeService): class ListParams(TypedDict): + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ ending_before: NotRequired[str] """ A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. diff --git a/stripe/_payment_intent.py b/stripe/_payment_intent.py index f3fdb865a..7f3731fbc 100644 --- a/stripe/_payment_intent.py +++ b/stripe/_payment_intent.py @@ -2094,6 +2094,12 @@ class ConfirmParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "PaymentIntent.ConfirmParamsPaymentMethodDataAmazonPay" ] @@ -4275,6 +4281,12 @@ class CreateParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "PaymentIntent.CreateParamsPaymentMethodDataAmazonPay" ] @@ -6452,6 +6464,12 @@ class ModifyParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "PaymentIntent.ModifyParamsPaymentMethodDataAmazonPay" ] diff --git a/stripe/_payment_intent_service.py b/stripe/_payment_intent_service.py index abd8e1e92..d6235fedd 100644 --- a/stripe/_payment_intent_service.py +++ b/stripe/_payment_intent_service.py @@ -245,6 +245,12 @@ class ConfirmParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "PaymentIntentService.ConfirmParamsPaymentMethodDataAmazonPay" ] @@ -2450,6 +2456,12 @@ class CreateParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "PaymentIntentService.CreateParamsPaymentMethodDataAmazonPay" ] @@ -4679,6 +4691,12 @@ class UpdateParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "PaymentIntentService.UpdateParamsPaymentMethodDataAmazonPay" ] diff --git a/stripe/_payment_method.py b/stripe/_payment_method.py index 99f07214d..c4d96a23e 100644 --- a/stripe/_payment_method.py +++ b/stripe/_payment_method.py @@ -1021,6 +1021,12 @@ class CreateParams(RequestOptions): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired["PaymentMethod.CreateParamsAmazonPay"] """ If this is a AmazonPay PaymentMethod, this hash contains details about the AmazonPay payment method. @@ -1672,6 +1678,12 @@ class ListParams(RequestOptions): """ class ModifyParams(RequestOptions): + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ billing_details: NotRequired[ "PaymentMethod.ModifyParamsBillingDetails" ] diff --git a/stripe/_payment_method_service.py b/stripe/_payment_method_service.py index 94d5cd2e3..86893c555 100644 --- a/stripe/_payment_method_service.py +++ b/stripe/_payment_method_service.py @@ -39,6 +39,12 @@ class CreateParams(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired["PaymentMethodService.CreateParamsAmazonPay"] """ If this is a AmazonPay PaymentMethod, this hash contains details about the AmazonPay payment method. @@ -702,6 +708,12 @@ class RetrieveParams(TypedDict): """ class UpdateParams(TypedDict): + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ billing_details: NotRequired[ "PaymentMethodService.UpdateParamsBillingDetails" ] diff --git a/stripe/_setup_intent.py b/stripe/_setup_intent.py index a58826d35..e8ff9cb0c 100644 --- a/stripe/_setup_intent.py +++ b/stripe/_setup_intent.py @@ -738,6 +738,12 @@ class ConfirmParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "SetupIntent.ConfirmParamsPaymentMethodDataAmazonPay" ] @@ -1814,6 +1820,12 @@ class CreateParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "SetupIntent.CreateParamsPaymentMethodDataAmazonPay" ] @@ -2859,6 +2871,12 @@ class ModifyParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "SetupIntent.ModifyParamsPaymentMethodDataAmazonPay" ] diff --git a/stripe/_setup_intent_service.py b/stripe/_setup_intent_service.py index 8c7398cd6..af9f2421f 100644 --- a/stripe/_setup_intent_service.py +++ b/stripe/_setup_intent_service.py @@ -132,6 +132,12 @@ class ConfirmParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "SetupIntentService.ConfirmParamsPaymentMethodDataAmazonPay" ] @@ -1248,6 +1254,12 @@ class CreateParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "SetupIntentService.CreateParamsPaymentMethodDataAmazonPay" ] @@ -2333,6 +2345,12 @@ class UpdateParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "SetupIntentService.UpdateParamsPaymentMethodDataAmazonPay" ] diff --git a/stripe/test_helpers/_confirmation_token_service.py b/stripe/test_helpers/_confirmation_token_service.py index d4f38616a..7a0333220 100644 --- a/stripe/test_helpers/_confirmation_token_service.py +++ b/stripe/test_helpers/_confirmation_token_service.py @@ -63,6 +63,12 @@ class CreateParamsPaymentMethodData(TypedDict): """ If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method. """ + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to `unspecified`. + """ amazon_pay: NotRequired[ "ConfirmationTokenService.CreateParamsPaymentMethodDataAmazonPay" ] From cc0e04ee0305e2e11fa05b3f81ca998a54b6be3f Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 17 Apr 2024 18:02:09 +0000 Subject: [PATCH 2/9] Update generated code for v964 --- OPENAPI_VERSION | 2 +- stripe/billing/_meter.py | 18 +++++++++--------- stripe/billing/_meter_event.py | 4 ++-- stripe/billing/_meter_event_service.py | 2 +- stripe/billing/_meter_event_summary.py | 8 ++++---- stripe/billing/_meter_event_summary_service.py | 4 ++-- stripe/billing/_meter_service.py | 6 +++--- 7 files changed, 22 insertions(+), 22 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index b158e42fd..f5a954059 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v963 \ No newline at end of file +v964 \ No newline at end of file diff --git a/stripe/billing/_meter.py b/stripe/billing/_meter.py index bc87cb308..2d4c2322d 100644 --- a/stripe/billing/_meter.py +++ b/stripe/billing/_meter.py @@ -36,7 +36,7 @@ class Meter( class CustomerMapping(StripeObject): event_payload_key: str """ - The key in the usage event payload to use for mapping the event to a customer. + The key in the meter event payload to use for mapping the event to a customer. """ type: Literal["by_id"] """ @@ -58,7 +58,7 @@ class StatusTransitions(StripeObject): class ValueSettings(StripeObject): event_payload_key: str """ - The key in the usage event payload to use as the value for this meter. + The key in the meter event payload to use as the value for this meter. """ class CreateParams(RequestOptions): @@ -76,11 +76,11 @@ class CreateParams(RequestOptions): """ event_name: str """ - The name of the usage event to record usage for. Corresponds with the `event_name` field on usage events. + The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events. """ event_time_window: NotRequired[Literal["day", "hour"]] """ - The time window to pre-aggregate usage events for, if any. + The time window to pre-aggregate meter events for, if any. """ expand: NotRequired[List[str]] """ @@ -88,7 +88,7 @@ class CreateParams(RequestOptions): """ value_settings: NotRequired["Meter.CreateParamsValueSettings"] """ - Fields that specify how to calculate a usage event's value. + Fields that specify how to calculate a meter event's value. """ class CreateParamsCustomerMapping(TypedDict): @@ -126,7 +126,7 @@ class ListEventSummariesParams(RequestOptions): """ end_time: int """ - The timestamp from when to stop aggregating usage events (exclusive). + The timestamp from when to stop aggregating meter events (exclusive). """ ending_before: NotRequired[str] """ @@ -142,7 +142,7 @@ class ListEventSummariesParams(RequestOptions): """ start_time: int """ - The timestamp from when to start aggregating usage events (inclusive). + The timestamp from when to start aggregating meter events (inclusive). """ starting_after: NotRequired[str] """ @@ -209,11 +209,11 @@ class RetrieveParams(RequestOptions): """ event_name: str """ - The name of the usage event to record usage for. Corresponds with the `event_name` field on usage events. + The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events. """ event_time_window: Optional[Literal["day", "hour"]] """ - The time window to pre-aggregate usage events for, if any. + The time window to pre-aggregate meter events for, if any. """ id: str """ diff --git a/stripe/billing/_meter_event.py b/stripe/billing/_meter_event.py index c25d4ec67..bd49da21f 100644 --- a/stripe/billing/_meter_event.py +++ b/stripe/billing/_meter_event.py @@ -31,7 +31,7 @@ class CreateParams(RequestOptions): """ payload: Dict[str, str] """ - The payload of the event. This must contain a field with the event's numerical value and a field to map the event to a customer. + The payload of the event. This must contain the fields corresponding to a meter's `customer_mapping.event_payload_key` (default is `stripe_customer_id`) and `value_settings.event_payload_key` (default is `value`). Read more about the [payload](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage#payload-key-overrides). """ timestamp: NotRequired[int] """ @@ -60,7 +60,7 @@ class CreateParams(RequestOptions): """ payload: Dict[str, str] """ - The payload of the event. + The payload of the event. This contains the fields corresponding to a meter's `customer_mapping.event_payload_key` (default is `stripe_customer_id`) and `value_settings.event_payload_key` (default is `value`). Read more about the [payload](https://stripe.com/docs/billing/subscriptions/usage-based/recording-usage#payload-key-overrides). """ timestamp: int """ diff --git a/stripe/billing/_meter_event_service.py b/stripe/billing/_meter_event_service.py index e2d06b5aa..c2e72e1de 100644 --- a/stripe/billing/_meter_event_service.py +++ b/stripe/billing/_meter_event_service.py @@ -23,7 +23,7 @@ class CreateParams(TypedDict): """ payload: Dict[str, str] """ - The payload of the event. This must contain a field with the event's numerical value and a field to map the event to a customer. + The payload of the event. This must contain the fields corresponding to a meter's `customer_mapping.event_payload_key` (default is `stripe_customer_id`) and `value_settings.event_payload_key` (default is `value`). Read more about the [payload](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage#payload-key-overrides). """ timestamp: NotRequired[int] """ diff --git a/stripe/billing/_meter_event_summary.py b/stripe/billing/_meter_event_summary.py index e3fe6cc3a..5b6fc0700 100644 --- a/stripe/billing/_meter_event_summary.py +++ b/stripe/billing/_meter_event_summary.py @@ -16,11 +16,11 @@ class MeterEventSummary(StripeObject): ] = "billing.meter_event_summary" aggregated_value: float """ - Aggregated value of all the events within start_time (inclusive) and end_time (inclusive). The aggregation strategy is defined on meter via `default_aggregation``. + Aggregated value of all the events within `start_time` (inclusive) and `end_time` (inclusive). The aggregation strategy is defined on meter via `default_aggregation`. """ end_time: int """ - End timestamp for this usage summary (inclusive). + End timestamp for this event summary (inclusive). """ id: str """ @@ -32,7 +32,7 @@ class MeterEventSummary(StripeObject): """ meter: str """ - The meter associated with this usage summary. + The meter associated with this event summary. """ object: Literal["billing.meter_event_summary"] """ @@ -40,5 +40,5 @@ class MeterEventSummary(StripeObject): """ start_time: int """ - Start timestamp for this usage summary (inclusive). + Start timestamp for this event summary (inclusive). """ diff --git a/stripe/billing/_meter_event_summary_service.py b/stripe/billing/_meter_event_summary_service.py index df51cd62f..73096be0e 100644 --- a/stripe/billing/_meter_event_summary_service.py +++ b/stripe/billing/_meter_event_summary_service.py @@ -17,7 +17,7 @@ class ListParams(TypedDict): """ end_time: int """ - The timestamp from when to stop aggregating usage events (exclusive). + The timestamp from when to stop aggregating meter events (exclusive). """ ending_before: NotRequired[str] """ @@ -33,7 +33,7 @@ class ListParams(TypedDict): """ start_time: int """ - The timestamp from when to start aggregating usage events (inclusive). + The timestamp from when to start aggregating meter events (inclusive). """ starting_after: NotRequired[str] """ diff --git a/stripe/billing/_meter_service.py b/stripe/billing/_meter_service.py index ca27d84d6..8cc87c6bb 100644 --- a/stripe/billing/_meter_service.py +++ b/stripe/billing/_meter_service.py @@ -34,11 +34,11 @@ class CreateParams(TypedDict): """ event_name: str """ - The name of the usage event to record usage for. Corresponds with the `event_name` field on usage events. + The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events. """ event_time_window: NotRequired[Literal["day", "hour"]] """ - The time window to pre-aggregate usage events for, if any. + The time window to pre-aggregate meter events for, if any. """ expand: NotRequired[List[str]] """ @@ -46,7 +46,7 @@ class CreateParams(TypedDict): """ value_settings: NotRequired["MeterService.CreateParamsValueSettings"] """ - Fields that specify how to calculate a usage event's value. + Fields that specify how to calculate a meter event's value. """ class CreateParamsCustomerMapping(TypedDict): From 6ec742da7e0b1866b70b93e94eb51362152e2e7d Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 17 Apr 2024 19:01:14 +0000 Subject: [PATCH 3/9] Update generated code for v966 --- OPENAPI_VERSION | 2 +- stripe/checkout/_session.py | 49 +++++++++++++++++++++++++++++ stripe/checkout/_session_service.py | 32 +++++++++++++++++++ 3 files changed, 82 insertions(+), 1 deletion(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index f5a954059..edc36cc54 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v964 \ No newline at end of file +v966 \ No newline at end of file diff --git a/stripe/checkout/_session.py b/stripe/checkout/_session.py index 561a67be3..d17dfd272 100644 --- a/stripe/checkout/_session.py +++ b/stripe/checkout/_session.py @@ -1031,6 +1031,18 @@ class PhoneNumberCollection(StripeObject): Indicates whether phone number collection is enabled for the session """ + class SavedPaymentMethodOptions(StripeObject): + allow_redisplay_filters: Optional[ + List[Literal["always", "limited", "unspecified"]] + ] + """ + Controls which payment methods are eligible to be redisplayed to returning customers. Corresponds to `allow_redisplay` on the payment method. + """ + payment_method_save: Optional[Literal["disabled", "enabled"]] + """ + Enable customers to choose if they wish to save their payment method for future use. + """ + class ShippingAddressCollection(StripeObject): allowed_countries: List[ Literal[ @@ -1663,6 +1675,12 @@ class CreateParams(RequestOptions): """ The ID of the payment method configuration to use with this Checkout session. """ + payment_method_data: NotRequired[ + "Session.CreateParamsPaymentMethodData" + ] + """ + This parameter allows you to set some attributes on the payment method created during a Checkout session. + """ payment_method_options: NotRequired[ "Session.CreateParamsPaymentMethodOptions" ] @@ -1743,6 +1761,12 @@ class CreateParams(RequestOptions): payment method's app or site. This parameter is required if ui_mode is `embedded` and redirect-based payment methods are enabled on the session. """ + saved_payment_method_options: NotRequired[ + "Session.CreateParamsSavedPaymentMethodOptions" + ] + """ + Controls saved payment method settings for the session. Only available in `payment` and `subscription` mode. + """ setup_intent_data: NotRequired["Session.CreateParamsSetupIntentData"] """ A subset of parameters to be passed to SetupIntent creation for Checkout Sessions in `setup` mode. @@ -2326,6 +2350,14 @@ class CreateParamsPaymentIntentDataTransferData(TypedDict): returned on the successful charge's `transfer` field. """ + class CreateParamsPaymentMethodData(TypedDict): + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + Allow redisplay will be set on the payment method on confirmation and indicates whether this payment method can be shown again to the customer in a checkout flow. Only set this field if you wish to override the allow_redisplay value determined by Checkout. + """ + class CreateParamsPaymentMethodOptions(TypedDict): acss_debit: NotRequired[ "Session.CreateParamsPaymentMethodOptionsAcssDebit" @@ -3017,6 +3049,18 @@ class CreateParamsPhoneNumberCollection(TypedDict): Set to `true` to enable phone number collection. """ + class CreateParamsSavedPaymentMethodOptions(TypedDict): + allow_redisplay_filters: NotRequired[ + List[Literal["always", "limited", "unspecified"]] + ] + """ + Controls which payment methods are eligible to be redisplayed to returning customers. Corresponds to `allow_redisplay` on the payment method. + """ + payment_method_save: NotRequired[Literal["disabled", "enabled"]] + """ + Enable customers to choose if they wish to save their payment method for future use. + """ + class CreateParamsSetupIntentData(TypedDict): description: NotRequired[str] """ @@ -3821,6 +3865,10 @@ class RetrieveParams(RequestOptions): """ Applies to Checkout Sessions with `ui_mode: embedded`. The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site. """ + saved_payment_method_options: Optional[SavedPaymentMethodOptions] + """ + Controls saved payment method settings for the session. Only available in `payment` and `subscription` mode. + """ setup_intent: Optional[ExpandableField["SetupIntent"]] """ The ID of the SetupIntent for Checkout Sessions in `setup` mode. @@ -4216,6 +4264,7 @@ async def retrieve_async( "payment_method_configuration_details": PaymentMethodConfigurationDetails, "payment_method_options": PaymentMethodOptions, "phone_number_collection": PhoneNumberCollection, + "saved_payment_method_options": SavedPaymentMethodOptions, "shipping_address_collection": ShippingAddressCollection, "shipping_cost": ShippingCost, "shipping_details": ShippingDetails, diff --git a/stripe/checkout/_session_service.py b/stripe/checkout/_session_service.py index 845bb21e4..6edb1dbf3 100644 --- a/stripe/checkout/_session_service.py +++ b/stripe/checkout/_session_service.py @@ -207,6 +207,12 @@ class CreateParams(TypedDict): """ The ID of the payment method configuration to use with this Checkout session. """ + payment_method_data: NotRequired[ + "SessionService.CreateParamsPaymentMethodData" + ] + """ + This parameter allows you to set some attributes on the payment method created during a Checkout session. + """ payment_method_options: NotRequired[ "SessionService.CreateParamsPaymentMethodOptions" ] @@ -287,6 +293,12 @@ class CreateParams(TypedDict): payment method's app or site. This parameter is required if ui_mode is `embedded` and redirect-based payment methods are enabled on the session. """ + saved_payment_method_options: NotRequired[ + "SessionService.CreateParamsSavedPaymentMethodOptions" + ] + """ + Controls saved payment method settings for the session. Only available in `payment` and `subscription` mode. + """ setup_intent_data: NotRequired[ "SessionService.CreateParamsSetupIntentData" ] @@ -884,6 +896,14 @@ class CreateParamsPaymentIntentDataTransferData(TypedDict): returned on the successful charge's `transfer` field. """ + class CreateParamsPaymentMethodData(TypedDict): + allow_redisplay: NotRequired[ + Literal["always", "limited", "unspecified"] + ] + """ + Allow redisplay will be set on the payment method on confirmation and indicates whether this payment method can be shown again to the customer in a checkout flow. Only set this field if you wish to override the allow_redisplay value determined by Checkout. + """ + class CreateParamsPaymentMethodOptions(TypedDict): acss_debit: NotRequired[ "SessionService.CreateParamsPaymentMethodOptionsAcssDebit" @@ -1607,6 +1627,18 @@ class CreateParamsPhoneNumberCollection(TypedDict): Set to `true` to enable phone number collection. """ + class CreateParamsSavedPaymentMethodOptions(TypedDict): + allow_redisplay_filters: NotRequired[ + List[Literal["always", "limited", "unspecified"]] + ] + """ + Controls which payment methods are eligible to be redisplayed to returning customers. Corresponds to `allow_redisplay` on the payment method. + """ + payment_method_save: NotRequired[Literal["disabled", "enabled"]] + """ + Enable customers to choose if they wish to save their payment method for future use. + """ + class CreateParamsSetupIntentData(TypedDict): description: NotRequired[str] """ From 11ab1d279b33b1d3eb14b7619d3351be0650e9ef Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 17 Apr 2024 20:00:34 +0000 Subject: [PATCH 4/9] Update generated code for v967 --- OPENAPI_VERSION | 2 +- stripe/issuing/_authorization.py | 4 ++-- stripe/issuing/_transaction.py | 10 +++++----- stripe/test_helpers/issuing/_authorization_service.py | 4 ++-- stripe/test_helpers/issuing/_transaction_service.py | 8 ++++---- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index edc36cc54..436e09fd1 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v966 \ No newline at end of file +v967 \ No newline at end of file diff --git a/stripe/issuing/_authorization.py b/stripe/issuing/_authorization.py index 491baa895..529120e10 100644 --- a/stripe/issuing/_authorization.py +++ b/stripe/issuing/_authorization.py @@ -416,9 +416,9 @@ class CaptureParamsPurchaseDetailsFuel(TypedDict): """ The type of fuel that was purchased. One of `diesel`, `unleaded_plus`, `unleaded_regular`, `unleaded_super`, or `other`. """ - unit: NotRequired[Literal["liter", "us_gallon"]] + unit: NotRequired[Literal["liter", "other", "us_gallon"]] """ - The units for `volume_decimal`. One of `us_gallon` or `liter`. + The units for `volume_decimal`. One of `liter`, `us_gallon`, or `other`. """ unit_cost_decimal: NotRequired[str] """ diff --git a/stripe/issuing/_transaction.py b/stripe/issuing/_transaction.py index 7746593dc..8609f87de 100644 --- a/stripe/issuing/_transaction.py +++ b/stripe/issuing/_transaction.py @@ -166,7 +166,7 @@ class Fuel(StripeObject): """ unit: str """ - The units for `volume_decimal`. One of `us_gallon` or `liter`. + The units for `volume_decimal`. One of `liter`, `us_gallon`, or `other`. """ unit_cost_decimal: str """ @@ -702,9 +702,9 @@ class CreateForceCaptureParamsPurchaseDetailsFuel(TypedDict): """ The type of fuel that was purchased. One of `diesel`, `unleaded_plus`, `unleaded_regular`, `unleaded_super`, or `other`. """ - unit: NotRequired[Literal["liter", "us_gallon"]] + unit: NotRequired[Literal["liter", "other", "us_gallon"]] """ - The units for `volume_decimal`. One of `us_gallon` or `liter`. + The units for `volume_decimal`. One of `liter`, `us_gallon`, or `other`. """ unit_cost_decimal: NotRequired[str] """ @@ -1193,9 +1193,9 @@ class CreateUnlinkedRefundParamsPurchaseDetailsFuel(TypedDict): """ The type of fuel that was purchased. One of `diesel`, `unleaded_plus`, `unleaded_regular`, `unleaded_super`, or `other`. """ - unit: NotRequired[Literal["liter", "us_gallon"]] + unit: NotRequired[Literal["liter", "other", "us_gallon"]] """ - The units for `volume_decimal`. One of `us_gallon` or `liter`. + The units for `volume_decimal`. One of `liter`, `us_gallon`, or `other`. """ unit_cost_decimal: NotRequired[str] """ diff --git a/stripe/test_helpers/issuing/_authorization_service.py b/stripe/test_helpers/issuing/_authorization_service.py index 438942ee4..bf41b79b8 100644 --- a/stripe/test_helpers/issuing/_authorization_service.py +++ b/stripe/test_helpers/issuing/_authorization_service.py @@ -124,9 +124,9 @@ class CaptureParamsPurchaseDetailsFuel(TypedDict): """ The type of fuel that was purchased. One of `diesel`, `unleaded_plus`, `unleaded_regular`, `unleaded_super`, or `other`. """ - unit: NotRequired[Literal["liter", "us_gallon"]] + unit: NotRequired[Literal["liter", "other", "us_gallon"]] """ - The units for `volume_decimal`. One of `us_gallon` or `liter`. + The units for `volume_decimal`. One of `liter`, `us_gallon`, or `other`. """ unit_cost_decimal: NotRequired[str] """ diff --git a/stripe/test_helpers/issuing/_transaction_service.py b/stripe/test_helpers/issuing/_transaction_service.py index 218470270..2f93fce32 100644 --- a/stripe/test_helpers/issuing/_transaction_service.py +++ b/stripe/test_helpers/issuing/_transaction_service.py @@ -471,9 +471,9 @@ class CreateForceCaptureParamsPurchaseDetailsFuel(TypedDict): """ The type of fuel that was purchased. One of `diesel`, `unleaded_plus`, `unleaded_regular`, `unleaded_super`, or `other`. """ - unit: NotRequired[Literal["liter", "us_gallon"]] + unit: NotRequired[Literal["liter", "other", "us_gallon"]] """ - The units for `volume_decimal`. One of `us_gallon` or `liter`. + The units for `volume_decimal`. One of `liter`, `us_gallon`, or `other`. """ unit_cost_decimal: NotRequired[str] """ @@ -962,9 +962,9 @@ class CreateUnlinkedRefundParamsPurchaseDetailsFuel(TypedDict): """ The type of fuel that was purchased. One of `diesel`, `unleaded_plus`, `unleaded_regular`, `unleaded_super`, or `other`. """ - unit: NotRequired[Literal["liter", "us_gallon"]] + unit: NotRequired[Literal["liter", "other", "us_gallon"]] """ - The units for `volume_decimal`. One of `us_gallon` or `liter`. + The units for `volume_decimal`. One of `liter`, `us_gallon`, or `other`. """ unit_cost_decimal: NotRequired[str] """ From 4e6824e08018ef3f86efaffc2edbaf44e339b855 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 17 Apr 2024 21:13:38 +0000 Subject: [PATCH 5/9] Update generated code for v967 --- stripe/_quote.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/stripe/_quote.py b/stripe/_quote.py index 7f82ad662..d4f5d71e2 100644 --- a/stripe/_quote.py +++ b/stripe/_quote.py @@ -1835,6 +1835,7 @@ def pdf( # pyright: ignore[reportGeneralTypeIssues] quote=sanitize_id(self.get("id")) ), params=params, + base_address="files", ), ) @@ -1887,6 +1888,7 @@ async def pdf_async( # pyright: ignore[reportGeneralTypeIssues] quote=sanitize_id(self.get("id")) ), params=params, + base_address="files", ), ) From ac862431ec82a6ae834fff5c68178fdc0ef23948 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Thu, 18 Apr 2024 01:15:12 +0000 Subject: [PATCH 6/9] Update generated code for v968 --- OPENAPI_VERSION | 2 +- stripe/billing/_meter.py | 2 +- stripe/billing/_meter_service.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 436e09fd1..471efc194 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v967 \ No newline at end of file +v968 \ No newline at end of file diff --git a/stripe/billing/_meter.py b/stripe/billing/_meter.py index 2d4c2322d..a6d0221b6 100644 --- a/stripe/billing/_meter.py +++ b/stripe/billing/_meter.py @@ -104,7 +104,7 @@ class CreateParamsCustomerMapping(TypedDict): class CreateParamsDefaultAggregation(TypedDict): formula: Literal["count", "sum"] """ - Specifies how events are aggregated. Allowed values are `count` to count the number of events, `sum` to sum each event's value, or `last` to use the last event's value. + Specifies how events are aggregated. Allowed values are `count` to count the number of events and `sum` to sum each event's value. """ class CreateParamsValueSettings(TypedDict): diff --git a/stripe/billing/_meter_service.py b/stripe/billing/_meter_service.py index 8cc87c6bb..a2e78e36a 100644 --- a/stripe/billing/_meter_service.py +++ b/stripe/billing/_meter_service.py @@ -62,7 +62,7 @@ class CreateParamsCustomerMapping(TypedDict): class CreateParamsDefaultAggregation(TypedDict): formula: Literal["count", "sum"] """ - Specifies how events are aggregated. Allowed values are `count` to count the number of events, `sum` to sum each event's value, or `last` to use the last event's value. + Specifies how events are aggregated. Allowed values are `count` to count the number of events and `sum` to sum each event's value. """ class CreateParamsValueSettings(TypedDict): From a9b40be5e1033ff47f9f5b2286283c649e20ffeb Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Thu, 18 Apr 2024 06:48:10 +0000 Subject: [PATCH 7/9] Update generated code for v969 --- OPENAPI_VERSION | 2 +- stripe/_invoice.py | 3764 ++++++++++++++++----- stripe/_invoice_service.py | 2260 +++++++++++-- stripe/_invoice_upcoming_lines_service.py | 574 +++- 4 files changed, 5421 insertions(+), 1179 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 471efc194..6031d9a63 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v968 \ No newline at end of file +v969 \ No newline at end of file diff --git a/stripe/_invoice.py b/stripe/_invoice.py index b47293b23..ff6018a11 100644 --- a/stripe/_invoice.py +++ b/stripe/_invoice.py @@ -1590,233 +1590,2412 @@ class CreateParamsTransferData(TypedDict): ID of an existing, connected Stripe account. """ - class DeleteParams(RequestOptions): - pass - - class FinalizeInvoiceParams(RequestOptions): - auto_advance: NotRequired[bool] + class CreatePreviewParams(RequestOptions): + automatic_tax: NotRequired["Invoice.CreatePreviewParamsAutomaticTax"] """ - Controls whether Stripe performs [automatic collection](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action. + Settings for automatic tax lookup for this invoice preview. + """ + coupon: NotRequired[str] + """ + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + """ + currency: NotRequired[str] + """ + The currency to preview this invoice in. Defaults to that of `customer` if not specified. + """ + customer: NotRequired[str] + """ + The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + """ + customer_details: NotRequired[ + "Invoice.CreatePreviewParamsCustomerDetails" + ] + """ + Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.CreatePreviewParamsDiscount]" + ] + """ + The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts. """ expand: NotRequired[List[str]] """ Specifies which fields in the response should be expanded. """ + invoice_items: NotRequired[ + List["Invoice.CreatePreviewParamsInvoiceItem"] + ] + """ + List of invoice items to add or update in the upcoming invoice preview. + """ + issuer: NotRequired["Invoice.CreatePreviewParamsIssuer"] + """ + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + """ + on_behalf_of: NotRequired["Literal['']|str"] + """ + The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. + """ + schedule: NotRequired[str] + """ + The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. + """ + schedule_details: NotRequired[ + "Invoice.CreatePreviewParamsScheduleDetails" + ] + """ + The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields. + """ + subscription: NotRequired[str] + """ + The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a `subscription_items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_items` is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions. + """ + subscription_details: NotRequired[ + "Invoice.CreatePreviewParamsSubscriptionDetails" + ] + """ + The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields. + """ - class ListParams(RequestOptions): - collection_method: NotRequired[ - Literal["charge_automatically", "send_invoice"] + class CreatePreviewParamsAutomaticTax(TypedDict): + enabled: bool + """ + Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. + """ + liability: NotRequired[ + "Invoice.CreatePreviewParamsAutomaticTaxLiability" ] """ - The collection method of the invoice to retrieve. Either `charge_automatically` or `send_invoice`. + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. """ - created: NotRequired["Invoice.ListParamsCreated|int"] + + class CreatePreviewParamsAutomaticTaxLiability(TypedDict): + account: NotRequired[str] """ - Only return invoices that were created during the given date interval. + The connected account being referenced when `type` is `account`. """ - customer: NotRequired[str] + type: Literal["account", "self"] """ - Only return invoices for the customer specified by this customer ID. + Type of the account referenced in the request. """ - due_date: NotRequired["Invoice.ListParamsDueDate|int"] - ending_before: NotRequired[str] + + class CreatePreviewParamsCustomerDetails(TypedDict): + address: NotRequired[ + "Literal['']|Invoice.CreatePreviewParamsCustomerDetailsAddress" + ] """ - A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. + The customer's address. """ - expand: NotRequired[List[str]] + shipping: NotRequired[ + "Literal['']|Invoice.CreatePreviewParamsCustomerDetailsShipping" + ] """ - Specifies which fields in the response should be expanded. + The customer's shipping information. Appears on invoices emailed to this customer. """ - limit: NotRequired[int] + tax: NotRequired["Invoice.CreatePreviewParamsCustomerDetailsTax"] """ - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + Tax details about the customer. """ - starting_after: NotRequired[str] + tax_exempt: NotRequired[ + "Literal['']|Literal['exempt', 'none', 'reverse']" + ] """ - A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. + The customer's tax exemption. One of `none`, `exempt`, or `reverse`. """ - status: NotRequired[ - Literal["draft", "open", "paid", "uncollectible", "void"] + tax_ids: NotRequired[ + List["Invoice.CreatePreviewParamsCustomerDetailsTaxId"] ] """ - The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://stripe.com/docs/billing/invoices/workflow#workflow-overview) + The customer's tax IDs. """ - subscription: NotRequired[str] + + class CreatePreviewParamsCustomerDetailsAddress(TypedDict): + city: NotRequired[str] """ - Only return invoices for the subscription specified by this subscription ID. + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. """ - class ListParamsCreated(TypedDict): - gt: NotRequired[int] + class CreatePreviewParamsCustomerDetailsShipping(TypedDict): + address: "Invoice.CreatePreviewParamsCustomerDetailsShippingAddress" """ - Minimum value to filter by (exclusive) + Customer shipping address. """ - gte: NotRequired[int] + name: str """ - Minimum value to filter by (inclusive) + Customer name. """ - lt: NotRequired[int] + phone: NotRequired[str] """ - Maximum value to filter by (exclusive) + Customer phone (including extension). """ - lte: NotRequired[int] + + class CreatePreviewParamsCustomerDetailsShippingAddress(TypedDict): + city: NotRequired[str] """ - Maximum value to filter by (inclusive) + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. """ - class ListParamsDueDate(TypedDict): - gt: NotRequired[int] + class CreatePreviewParamsCustomerDetailsTax(TypedDict): + ip_address: NotRequired["Literal['']|str"] """ - Minimum value to filter by (exclusive) + A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes. """ - gte: NotRequired[int] + + class CreatePreviewParamsCustomerDetailsTaxId(TypedDict): + type: Literal[ + "ad_nrt", + "ae_trn", + "ar_cuit", + "au_abn", + "au_arn", + "bg_uic", + "bh_vat", + "bo_tin", + "br_cnpj", + "br_cpf", + "ca_bn", + "ca_gst_hst", + "ca_pst_bc", + "ca_pst_mb", + "ca_pst_sk", + "ca_qst", + "ch_vat", + "cl_tin", + "cn_tin", + "co_nit", + "cr_tin", + "do_rcn", + "ec_ruc", + "eg_tin", + "es_cif", + "eu_oss_vat", + "eu_vat", + "gb_vat", + "ge_vat", + "hk_br", + "hu_tin", + "id_npwp", + "il_vat", + "in_gst", + "is_vat", + "jp_cn", + "jp_rn", + "jp_trn", + "ke_pin", + "kr_brn", + "kz_bin", + "li_uid", + "mx_rfc", + "my_frp", + "my_itn", + "my_sst", + "ng_tin", + "no_vat", + "no_voec", + "nz_gst", + "om_vat", + "pe_ruc", + "ph_tin", + "ro_tin", + "rs_pib", + "ru_inn", + "ru_kpp", + "sa_vat", + "sg_gst", + "sg_uen", + "si_tin", + "sv_nit", + "th_vat", + "tr_tin", + "tw_vat", + "ua_vat", + "us_ein", + "uy_ruc", + "ve_rif", + "vn_tin", + "za_vat", + ] """ - Minimum value to filter by (inclusive) + Type of the tax ID, one of `ad_nrt`, `ae_trn`, `ar_cuit`, `au_abn`, `au_arn`, `bg_uic`, `bh_vat`, `bo_tin`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_vat`, `cl_tin`, `cn_tin`, `co_nit`, `cr_tin`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `eu_oss_vat`, `eu_vat`, `gb_vat`, `ge_vat`, `hk_br`, `hu_tin`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kr_brn`, `kz_bin`, `li_uid`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sv_nit`, `th_vat`, `tr_tin`, `tw_vat`, `ua_vat`, `us_ein`, `uy_ruc`, `ve_rif`, `vn_tin`, or `za_vat` """ - lt: NotRequired[int] + value: str """ - Maximum value to filter by (exclusive) + Value of the tax ID. """ - lte: NotRequired[int] + + class CreatePreviewParamsDiscount(TypedDict): + coupon: NotRequired[str] """ - Maximum value to filter by (inclusive) + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsInvoiceItem(TypedDict): + amount: NotRequired[int] + """ + The integer amount in cents (or local equivalent) of previewed invoice item. + """ + currency: NotRequired[str] + """ + 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). Only applicable to new invoice items. + """ + description: NotRequired[str] + """ + An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + """ + discountable: NotRequired[bool] + """ + Explicitly controls whether discounts apply to this invoice item. Defaults to true, except for negative invoice items. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.CreatePreviewParamsInvoiceItemDiscount]" + ] + """ + The coupons to redeem into discounts for the invoice item in the preview. + """ + invoiceitem: NotRequired[str] + """ + The ID of the invoice item to update in preview. If not specified, a new invoice item will be added to the preview of the upcoming invoice. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + period: NotRequired["Invoice.CreatePreviewParamsInvoiceItemPeriod"] + """ + The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "Invoice.CreatePreviewParamsInvoiceItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Non-negative integer. The quantity of units for the invoice item. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + tax_code: NotRequired["Literal['']|str"] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates that apply to the item. When set, any `default_tax_rates` do not apply to this item. + """ + unit_amount: NotRequired[int] + """ + The integer unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer's account, pass a negative unit_amount. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsInvoiceItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsInvoiceItemPeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class CreatePreviewParamsInvoiceItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsIssuer(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class CreatePreviewParamsScheduleDetails(TypedDict): + end_behavior: NotRequired[Literal["cancel", "release"]] + """ + Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running. `cancel` will end the subscription schedule and cancel the underlying subscription. + """ + phases: NotRequired[ + List["Invoice.CreatePreviewParamsScheduleDetailsPhase"] + ] + """ + List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the `end_date` of one phase will always equal the `start_date` of the next phase. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + In cases where the `schedule_details` params update the currently active phase, specifies if and how to prorate at the time of the request. + """ + + class CreatePreviewParamsScheduleDetailsPhase(TypedDict): + add_invoice_items: NotRequired[ + List[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItem" + ] + ] + """ + A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. You may pass up to 20 items. + """ + application_fee_percent: NotRequired[float] + """ + 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 application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions). + """ + automatic_tax: NotRequired[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseAutomaticTax" + ] + """ + Automatic tax settings for this phase. + """ + billing_cycle_anchor: NotRequired[Literal["automatic", "phase_start"]] + """ + Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle). + """ + billing_thresholds: NotRequired[ + "Literal['']|Invoice.CreatePreviewParamsScheduleDetailsPhaseBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds. + """ + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] + """ + Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically` on creation. + """ + coupon: NotRequired[str] + """ + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + """ + currency: NotRequired[str] + """ + 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). + """ + default_payment_method: NotRequired[str] + """ + ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer's invoice settings. + """ + default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will set the Subscription's [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates), which means they will be the Invoice's [`default_tax_rates`](https://stripe.com/docs/api/invoices/create#create_invoice-default_tax_rates) for any Invoices issued by the Subscription during this Phase. + """ + description: NotRequired["Literal['']|str"] + """ + Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.CreatePreviewParamsScheduleDetailsPhaseDiscount]" + ] + """ + The coupons to redeem into discounts for the schedule phase. If not specified, inherits the discount from the subscription's customer. Pass an empty string to avoid inheriting any discounts. + """ + end_date: NotRequired["int|Literal['now']"] + """ + The date at which this phase of the subscription schedule ends. If set, `iterations` must not be set. + """ + invoice_settings: NotRequired[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseInvoiceSettings" + ] + """ + All invoices will be billed using the specified settings. + """ + items: List["Invoice.CreatePreviewParamsScheduleDetailsPhaseItem"] + """ + List of configuration items, each with an attached price, to apply during this phase of the subscription schedule. + """ + iterations: NotRequired[int] + """ + Integer representing the multiplier applied to the price interval. For example, `iterations=2` applied to a price with `interval=month` and `interval_count=3` results in a phase of duration `2 * 3 months = 6 months`. If set, `end_date` must not be set. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a phase. Metadata on a schedule's phase will update the underlying subscription's `metadata` when the phase is entered, adding new keys and replacing existing keys in the subscription's `metadata`. Individual keys in the subscription's `metadata` can be unset by posting an empty value to them in the phase's `metadata`. To unset all keys in the subscription's `metadata`, update the subscription directly or unset every key individually from the phase's `metadata`. + """ + on_behalf_of: NotRequired[str] + """ + The account on behalf of which to charge, for each of the associated subscription's invoices. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + Whether the subscription schedule will create [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when transitioning to this phase. The default value is `create_prorations`. This setting controls prorations when a phase is started asynchronously and it is persisted as a field on the phase. It's different from the request-level [proration_behavior](https://stripe.com/docs/api/subscription_schedules/update#update_subscription_schedule-proration_behavior) parameter which controls what happens if the update request affects the billing configuration of the current phase. + """ + start_date: NotRequired["int|Literal['now']"] + """ + The date at which this phase of the subscription schedule starts or `now`. Must be set on the first phase. + """ + transfer_data: NotRequired[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseTransferData" + ] + """ + The data with which to automatically create a Transfer for each of the associated subscription's invoices. + """ + trial: NotRequired[bool] + """ + If set to true the entire phase is counted as a trial and the customer will not be charged for any fees. + """ + trial_end: NotRequired["int|Literal['now']"] + """ + Sets the phase to trialing from the start date to this date. Must be before the phase end date, can not be combined with `trial` + """ + + class CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItem(TypedDict): + discounts: NotRequired[ + List[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItemDiscount" + ] + ] + """ + The coupons to redeem into discounts for the item. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for this item. Defaults to 1. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates which apply to the item. When set, the `default_tax_rates` do not apply to this item. + """ + + class CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItemDiscount( + TypedDict, + ): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItemPriceData( + TypedDict, + ): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsScheduleDetailsPhaseAutomaticTax(TypedDict): + enabled: bool + """ + Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription. + """ + liability: NotRequired[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseAutomaticTaxLiability" + ] + """ + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. + """ + + class CreatePreviewParamsScheduleDetailsPhaseAutomaticTaxLiability( + TypedDict, + ): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class CreatePreviewParamsScheduleDetailsPhaseBillingThresholds(TypedDict): + amount_gte: NotRequired[int] + """ + Monetary threshold that triggers the subscription to advance to a new billing period + """ + reset_billing_cycle_anchor: NotRequired[bool] + """ + Indicates if the `billing_cycle_anchor` should be reset when a threshold is reached. If true, `billing_cycle_anchor` will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged. + """ + + class CreatePreviewParamsScheduleDetailsPhaseDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsScheduleDetailsPhaseInvoiceSettings(TypedDict): + account_tax_ids: NotRequired["Literal['']|List[str]"] + """ + 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. + """ + days_until_due: NotRequired[int] + """ + Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be `null` for subscription schedules where `billing=charge_automatically`. + """ + issuer: NotRequired[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseInvoiceSettingsIssuer" + ] + """ + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + """ + + class CreatePreviewParamsScheduleDetailsPhaseInvoiceSettingsIssuer( + TypedDict, + ): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class CreatePreviewParamsScheduleDetailsPhaseItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|Invoice.CreatePreviewParamsScheduleDetailsPhaseItemBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.CreatePreviewParamsScheduleDetailsPhaseItemDiscount]" + ] + """ + The coupons to redeem into discounts for the subscription item. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a configuration item. Metadata on a configuration item will update the underlying subscription item's `metadata` when the phase is entered, adding new keys and replacing existing keys. Individual keys in the subscription item's `metadata` can be unset by posting an empty value to them in the configuration item's `metadata`. To unset all keys in the subscription item's `metadata`, update the subscription item directly or unset every key individually from the configuration item's `metadata`. + """ + plan: NotRequired[str] + """ + The plan ID to subscribe to. You may specify the same ID in `plan` and `price`. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "Invoice.CreatePreviewParamsScheduleDetailsPhaseItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for the given price. Can be set only if the price's `usage_type` is `licensed` and not `metered`. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. + """ + + class CreatePreviewParamsScheduleDetailsPhaseItemBillingThresholds( + TypedDict, + ): + usage_gte: int + """ + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) + """ + + class CreatePreviewParamsScheduleDetailsPhaseItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsScheduleDetailsPhaseItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + recurring: "Invoice.CreatePreviewParamsScheduleDetailsPhaseItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsScheduleDetailsPhaseItemPriceDataRecurring( + TypedDict, + ): + interval: Literal["day", "month", "week", "year"] + """ + Specifies billing frequency. Either `day`, `week`, `month` or `year`. + """ + interval_count: NotRequired[int] + """ + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). + """ + + class CreatePreviewParamsScheduleDetailsPhaseTransferData(TypedDict): + amount_percent: NotRequired[float] + """ + 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. + """ + destination: str + """ + ID of an existing, connected Stripe account. + """ + + class CreatePreviewParamsSubscriptionDetails(TypedDict): + billing_cycle_anchor: NotRequired["Literal['now', 'unchanged']|int"] + """ + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. + """ + cancel_at: NotRequired["Literal['']|int"] + """ + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. + """ + cancel_at_period_end: NotRequired[bool] + """ + Boolean indicating whether this subscription should cancel at the end of the current period. + """ + cancel_now: NotRequired[bool] + """ + This simulates the subscription being canceled or expired immediately. + """ + default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. + """ + items: NotRequired[ + List["Invoice.CreatePreviewParamsSubscriptionDetailsItem"] + ] + """ + A list of up to 20 subscription items, each with an attached price. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. + """ + proration_date: NotRequired[int] + """ + If previewing an update to a subscription, and doing proration, `subscription_details.proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_details.items`, or `subscription_details.trial_end` are required. Also, `subscription_details.proration_behavior` cannot be set to 'none'. + """ + resume_at: NotRequired[Literal["now"]] + """ + For paused subscriptions, setting `subscription_details.resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. + """ + start_date: NotRequired[int] + """ + Date a subscription is intended to start (can be future or past). + """ + trial_end: NotRequired["Literal['now']|int"] + """ + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_details.items` or `subscription` is required. + """ + + class CreatePreviewParamsSubscriptionDetailsItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|Invoice.CreatePreviewParamsSubscriptionDetailsItemBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. + """ + clear_usage: NotRequired[bool] + """ + Delete all usage for a given subscription item. Allowed only when `deleted` is set to `true` and the current plan's `usage_type` is `metered`. + """ + deleted: NotRequired[bool] + """ + A flag that, if set to `true`, will delete the specified item. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.CreatePreviewParamsSubscriptionDetailsItemDiscount]" + ] + """ + The coupons to redeem into discounts for the subscription item. + """ + id: NotRequired[str] + """ + Subscription item to update. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + plan: NotRequired[str] + """ + Plan ID for this item, as a string. + """ + price: NotRequired[str] + """ + The ID of the price object. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided. + """ + price_data: NotRequired[ + "Invoice.CreatePreviewParamsSubscriptionDetailsItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for this item. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. + """ + + class CreatePreviewParamsSubscriptionDetailsItemBillingThresholds( + TypedDict, + ): + usage_gte: int + """ + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) + """ + + class CreatePreviewParamsSubscriptionDetailsItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsSubscriptionDetailsItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + recurring: "Invoice.CreatePreviewParamsSubscriptionDetailsItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsSubscriptionDetailsItemPriceDataRecurring( + TypedDict, + ): + interval: Literal["day", "month", "week", "year"] + """ + Specifies billing frequency. Either `day`, `week`, `month` or `year`. + """ + interval_count: NotRequired[int] + """ + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). + """ + + class DeleteParams(RequestOptions): + pass + + class FinalizeInvoiceParams(RequestOptions): + auto_advance: NotRequired[bool] + """ + Controls whether Stripe performs [automatic collection](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action. + """ + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + class ListParams(RequestOptions): + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] + """ + The collection method of the invoice to retrieve. Either `charge_automatically` or `send_invoice`. + """ + created: NotRequired["Invoice.ListParamsCreated|int"] + """ + Only return invoices that were created during the given date interval. + """ + customer: NotRequired[str] + """ + Only return invoices for the customer specified by this customer ID. + """ + due_date: NotRequired["Invoice.ListParamsDueDate|int"] + ending_before: NotRequired[str] + """ + A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. + """ + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + limit: NotRequired[int] + """ + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + """ + starting_after: NotRequired[str] + """ + A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. + """ + status: NotRequired[ + Literal["draft", "open", "paid", "uncollectible", "void"] + ] + """ + The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://stripe.com/docs/billing/invoices/workflow#workflow-overview) + """ + subscription: NotRequired[str] + """ + Only return invoices for the subscription specified by this subscription ID. + """ + + class ListParamsCreated(TypedDict): + gt: NotRequired[int] + """ + Minimum value to filter by (exclusive) + """ + gte: NotRequired[int] + """ + Minimum value to filter by (inclusive) + """ + lt: NotRequired[int] + """ + Maximum value to filter by (exclusive) + """ + lte: NotRequired[int] + """ + Maximum value to filter by (inclusive) + """ + + class ListParamsDueDate(TypedDict): + gt: NotRequired[int] + """ + Minimum value to filter by (exclusive) + """ + gte: NotRequired[int] + """ + Minimum value to filter by (inclusive) + """ + lt: NotRequired[int] + """ + Maximum value to filter by (exclusive) + """ + lte: NotRequired[int] + """ + Maximum value to filter by (inclusive) + """ + + class MarkUncollectibleParams(RequestOptions): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + class ModifyParams(RequestOptions): + account_tax_ids: NotRequired["Literal['']|List[str]"] + """ + The account tax IDs associated with the invoice. Only editable when the invoice is a draft. + """ + application_fee_amount: NotRequired[int] + """ + A fee in cents (or local equivalent) that will be applied to the invoice and transferred to the application owner's Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee. For more information, see the application fees [documentation](https://stripe.com/docs/billing/invoices/connect#collecting-fees). + """ + auto_advance: NotRequired[bool] + """ + Controls whether Stripe performs [automatic collection](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection) of the invoice. + """ + automatic_tax: NotRequired["Invoice.ModifyParamsAutomaticTax"] + """ + Settings for automatic tax lookup for this invoice. + """ + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] + """ + Either `charge_automatically` or `send_invoice`. This field can be updated only on `draft` invoices. + """ + custom_fields: NotRequired[ + "Literal['']|List[Invoice.ModifyParamsCustomField]" + ] + """ + A list of up to 4 custom fields to be displayed on the invoice. If a value for `custom_fields` is specified, the list specified will replace the existing custom field list on this invoice. Pass an empty string to remove previously-defined fields. + """ + days_until_due: NotRequired[int] + """ + The number of days from which the invoice is created until it is due. Only valid for invoices where `collection_method=send_invoice`. This field can only be updated on `draft` invoices. + """ + default_payment_method: NotRequired[str] + """ + ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings. + """ + default_source: NotRequired["Literal['']|str"] + """ + ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source. + """ + default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates that will apply to any line item that does not have `tax_rates` set. Pass an empty string to remove previously-defined tax rates. + """ + description: NotRequired[str] + """ + An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.ModifyParamsDiscount]" + ] + """ + The discounts that will apply to the invoice. Pass an empty string to remove previously-defined discounts. + """ + due_date: NotRequired[int] + """ + The date on which payment for this invoice is due. Only valid for invoices where `collection_method=send_invoice`. This field can only be updated on `draft` invoices. + """ + effective_at: NotRequired["Literal['']|int"] + """ + The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt. + """ + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + footer: NotRequired[str] + """ + Footer to be displayed on the invoice. + """ + issuer: NotRequired["Invoice.ModifyParamsIssuer"] + """ + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + number: NotRequired["Literal['']|str"] + """ + Set the number for this invoice. If no number is present then a number will be assigned automatically when the invoice is finalized. In many markets, regulations require invoices to be unique, sequential and / or gapless. You are responsible for ensuring this is true across all your different invoicing systems in the event that you edit the invoice number using our API. If you use only Stripe for your invoices and do not change invoice numbers, Stripe handles this aspect of compliance for you automatically. + """ + on_behalf_of: NotRequired["Literal['']|str"] + """ + The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. + """ + payment_settings: NotRequired["Invoice.ModifyParamsPaymentSettings"] + """ + Configuration settings for the PaymentIntent that is generated when the invoice is finalized. + """ + rendering: NotRequired["Invoice.ModifyParamsRendering"] + """ + The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page. + """ + shipping_cost: NotRequired[ + "Literal['']|Invoice.ModifyParamsShippingCost" + ] + """ + Settings for the cost of shipping for this invoice. + """ + shipping_details: NotRequired[ + "Literal['']|Invoice.ModifyParamsShippingDetails" + ] + """ + Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer. + """ + statement_descriptor: NotRequired[str] + """ + Extra information about a charge for the customer's credit card statement. It must contain at least one letter. If not specified and this invoice is part of a subscription, the default `statement_descriptor` will be set to the first subscription item's product's `statement_descriptor`. + """ + transfer_data: NotRequired[ + "Literal['']|Invoice.ModifyParamsTransferData" + ] + """ + If specified, the funds from the invoice will be transferred to the destination and the ID of the resulting transfer will be found on the invoice's charge. This will be unset if you POST an empty value. + """ + + class ModifyParamsAutomaticTax(TypedDict): + enabled: bool + """ + Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. + """ + liability: NotRequired["Invoice.ModifyParamsAutomaticTaxLiability"] + """ + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. + """ + + class ModifyParamsAutomaticTaxLiability(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class ModifyParamsCustomField(TypedDict): + name: str + """ + The name of the custom field. This may be up to 40 characters. + """ + value: str + """ + The value of the custom field. This may be up to 140 characters. + """ + + class ModifyParamsDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class ModifyParamsIssuer(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class ModifyParamsPaymentSettings(TypedDict): + default_mandate: NotRequired["Literal['']|str"] + """ + ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the invoice's default_payment_method or default_source, if set. + """ + payment_method_options: NotRequired[ + "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptions" + ] + """ + Payment-method-specific configuration to provide to the invoice's PaymentIntent. + """ + payment_method_types: NotRequired[ + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'sepa_credit_transfer', 'sepa_debit', 'sofort', 'us_bank_account', 'wechat_pay']]" + ] + """ + The list of payment method types (e.g. card) to provide to the invoice's PaymentIntent. If not set, Stripe attempts to automatically determine the types to use by looking at the invoice's default payment method, the subscription's default payment method, the customer's default payment method, and your [invoice template settings](https://dashboard.stripe.com/settings/billing/invoice). + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptions(TypedDict): + acss_debit: NotRequired[ + "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsAcssDebit" + ] + """ + If paying by `acss_debit`, this sub-hash contains details about the Canadian pre-authorized debit payment method options to pass to the invoice's PaymentIntent. + """ + bancontact: NotRequired[ + "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsBancontact" + ] + """ + If paying by `bancontact`, this sub-hash contains details about the Bancontact payment method options to pass to the invoice's PaymentIntent. + """ + card: NotRequired[ + "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCard" + ] + """ + If paying by `card`, this sub-hash contains details about the Card payment method options to pass to the invoice's PaymentIntent. + """ + customer_balance: NotRequired[ + "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalance" + ] + """ + If paying by `customer_balance`, this sub-hash contains details about the Bank transfer payment method options to pass to the invoice's PaymentIntent. + """ + konbini: NotRequired[ + "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsKonbini" + ] + """ + If paying by `konbini`, this sub-hash contains details about the Konbini payment method options to pass to the invoice's PaymentIntent. + """ + sepa_debit: NotRequired[ + "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsSepaDebit" + ] + """ + If paying by `sepa_debit`, this sub-hash contains details about the SEPA Direct Debit payment method options to pass to the invoice's PaymentIntent. + """ + us_bank_account: NotRequired[ + "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsUsBankAccount" + ] + """ + If paying by `us_bank_account`, this sub-hash contains details about the ACH direct debit payment method options to pass to the invoice's PaymentIntent. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsAcssDebit(TypedDict): + mandate_options: NotRequired[ + "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsAcssDebitMandateOptions" + ] + """ + Additional fields for Mandate creation + """ + verification_method: NotRequired[ + Literal["automatic", "instant", "microdeposits"] + ] + """ + Verification method for the intent + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsAcssDebitMandateOptions( + TypedDict, + ): + transaction_type: NotRequired[Literal["business", "personal"]] + """ + Transaction type of the mandate. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsBancontact(TypedDict): + preferred_language: NotRequired[Literal["de", "en", "fr", "nl"]] + """ + Preferred language of the Bancontact authorization page that the customer is redirected to. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsCard(TypedDict): + installments: NotRequired[ + "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCardInstallments" + ] + """ + Installment configuration for payments attempted on this invoice (Mexico Only). + + For more information, see the [installments integration guide](https://stripe.com/docs/payments/installments). + """ + request_three_d_secure: NotRequired[ + Literal["any", "automatic", "challenge"] + ] + """ + 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. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsCardInstallments( + TypedDict, + ): + enabled: NotRequired[bool] + """ + Setting to true enables installments for this invoice. + Setting to false will prevent any selected plan from applying to a payment. + """ + plan: NotRequired[ + "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCardInstallmentsPlan" + ] + """ + The selected installment plan to use for this invoice. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsCardInstallmentsPlan( + TypedDict, + ): + count: int + """ + For `fixed_count` installment plans, this is the number of installment payments your customer will make to their credit card. + """ + interval: Literal["month"] + """ + For `fixed_count` installment plans, this is the interval between installment payments your customer will make to their credit card. + One of `month`. + """ + type: Literal["fixed_count"] + """ + Type of installment plan, one of `fixed_count`. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalance( + TypedDict, + ): + bank_transfer: NotRequired[ + "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalanceBankTransfer" + ] + """ + Configuration for the bank transfer funding type, if the `funding_type` is set to `bank_transfer`. + """ + funding_type: NotRequired[str] + """ + The funding method type to be used when there are not enough funds in the customer balance. Permitted values include: `bank_transfer`. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalanceBankTransfer( + TypedDict, + ): + eu_bank_transfer: NotRequired[ + "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalanceBankTransferEuBankTransfer" + ] + """ + Configuration for eu_bank_transfer funding type. + """ + type: NotRequired[str] + """ + The bank transfer type that can be used for funding. Permitted values include: `eu_bank_transfer`, `gb_bank_transfer`, `jp_bank_transfer`, `mx_bank_transfer`, or `us_bank_transfer`. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalanceBankTransferEuBankTransfer( + TypedDict, + ): + country: str + """ + The desired country code of the bank account information. Permitted values include: `BE`, `DE`, `ES`, `FR`, `IE`, or `NL`. + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsKonbini(TypedDict): + pass + + class ModifyParamsPaymentSettingsPaymentMethodOptionsSepaDebit(TypedDict): + pass + + class ModifyParamsPaymentSettingsPaymentMethodOptionsUsBankAccount( + TypedDict, + ): + financial_connections: NotRequired[ + "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsUsBankAccountFinancialConnections" + ] + """ + Additional fields for Financial Connections Session creation + """ + verification_method: NotRequired[ + Literal["automatic", "instant", "microdeposits"] + ] + """ + Verification method for the intent + """ + + class ModifyParamsPaymentSettingsPaymentMethodOptionsUsBankAccountFinancialConnections( + TypedDict, + ): + permissions: NotRequired[ + List[ + Literal[ + "balances", "ownership", "payment_method", "transactions" + ] + ] + ] + """ + The list of permissions to request. If this parameter is passed, the `payment_method` permission must be included. Valid permissions include: `balances`, `ownership`, `payment_method`, and `transactions`. + """ + prefetch: NotRequired[ + List[Literal["balances", "ownership", "transactions"]] + ] + """ + List of data features that you would like to retrieve upon account creation. + """ + + class ModifyParamsRendering(TypedDict): + amount_tax_display: NotRequired[ + "Literal['']|Literal['exclude_tax', 'include_inclusive_tax']" + ] + """ + How line-item prices and amounts will be displayed with respect to tax on invoice PDFs. One of `exclude_tax` or `include_inclusive_tax`. `include_inclusive_tax` will include inclusive tax (and exclude exclusive tax) in invoice PDF amounts. `exclude_tax` will exclude all tax (inclusive and exclusive alike) from invoice PDF amounts. + """ + pdf: NotRequired["Invoice.ModifyParamsRenderingPdf"] + """ + Invoice pdf rendering options + """ + + class ModifyParamsRenderingPdf(TypedDict): + page_size: NotRequired[Literal["a4", "auto", "letter"]] + """ + Page size for invoice PDF. Can be set to `a4`, `letter`, or `auto`. + If set to `auto`, invoice PDF page size defaults to `a4` for customers with + Japanese locale and `letter` for customers with other locales. + """ + + class ModifyParamsShippingCost(TypedDict): + shipping_rate: NotRequired[str] + """ + The ID of the shipping rate to use for this order. + """ + shipping_rate_data: NotRequired[ + "Invoice.ModifyParamsShippingCostShippingRateData" + ] + """ + Parameters to create a new ad-hoc shipping rate for this order. + """ + + class ModifyParamsShippingCostShippingRateData(TypedDict): + delivery_estimate: NotRequired[ + "Invoice.ModifyParamsShippingCostShippingRateDataDeliveryEstimate" + ] + """ + The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions. + """ + display_name: str + """ + The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions. + """ + fixed_amount: NotRequired[ + "Invoice.ModifyParamsShippingCostShippingRateDataFixedAmount" + ] + """ + Describes a fixed amount to charge for shipping. Must be present if type is `fixed_amount`. + """ + metadata: NotRequired[Dict[str, str]] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. + """ + tax_code: NotRequired[str] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. The Shipping tax code is `txcd_92010001`. + """ + type: NotRequired[Literal["fixed_amount"]] + """ + The type of calculation to use on the shipping rate. Can only be `fixed_amount` for now. + """ + + class ModifyParamsShippingCostShippingRateDataDeliveryEstimate(TypedDict): + maximum: NotRequired[ + "Invoice.ModifyParamsShippingCostShippingRateDataDeliveryEstimateMaximum" + ] + """ + The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. + """ + minimum: NotRequired[ + "Invoice.ModifyParamsShippingCostShippingRateDataDeliveryEstimateMinimum" + ] + """ + The lower bound of the estimated range. If empty, represents no lower bound. + """ + + class ModifyParamsShippingCostShippingRateDataDeliveryEstimateMaximum( + TypedDict, + ): + unit: Literal["business_day", "day", "hour", "month", "week"] + """ + A unit of time. + """ + value: int + """ + Must be greater than 0. + """ + + class ModifyParamsShippingCostShippingRateDataDeliveryEstimateMinimum( + TypedDict, + ): + unit: Literal["business_day", "day", "hour", "month", "week"] + """ + A unit of time. + """ + value: int + """ + Must be greater than 0. + """ + + class ModifyParamsShippingCostShippingRateDataFixedAmount(TypedDict): + amount: int + """ + A non-negative integer in cents representing how much to charge. + """ + currency: str + """ + 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_options: NotRequired[ + Dict[ + str, + "Invoice.ModifyParamsShippingCostShippingRateDataFixedAmountCurrencyOptions", + ] + ] + """ + Shipping rates defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies). + """ + + class ModifyParamsShippingCostShippingRateDataFixedAmountCurrencyOptions( + TypedDict, + ): + amount: int + """ + A non-negative integer in cents representing how much to charge. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. + """ + + class ModifyParamsShippingDetails(TypedDict): + address: "Invoice.ModifyParamsShippingDetailsAddress" + """ + Shipping address + """ + name: str + """ + Recipient name. + """ + phone: NotRequired["Literal['']|str"] + """ + Recipient phone (including extension) + """ + + class ModifyParamsShippingDetailsAddress(TypedDict): + city: NotRequired[str] + """ + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. + """ + + class ModifyParamsTransferData(TypedDict): + amount: NotRequired[int] + """ + The amount that will be transferred automatically when the invoice is paid. If no amount is set, the full amount is transferred. + """ + destination: str + """ + ID of an existing, connected Stripe account. + """ + + class PayParams(RequestOptions): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + forgive: NotRequired[bool] + """ + In cases where the source used to pay the invoice has insufficient funds, passing `forgive=true` controls whether a charge should be attempted for the full amount available on the source, up to the amount to fully pay the invoice. This effectively forgives the difference between the amount available on the source and the amount due. + + Passing `forgive=false` will fail the charge if the source hasn't been pre-funded with the right amount. An example for this case is with ACH Credit Transfers and wires: if the amount wired is less than the amount due by a small amount, you might want to forgive the difference. Defaults to `false`. + """ + mandate: NotRequired["Literal['']|str"] + """ + ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the payment_method param or the invoice's default_payment_method or default_source, if set. + """ + off_session: NotRequired[bool] + """ + Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `true` (off-session). + """ + paid_out_of_band: NotRequired[bool] + """ + Boolean representing whether an invoice is paid outside of Stripe. This will result in no charge being made. Defaults to `false`. + """ + payment_method: NotRequired[str] + """ + A PaymentMethod to be charged. The PaymentMethod must be the ID of a PaymentMethod belonging to the customer associated with the invoice being paid. + """ + source: NotRequired[str] + """ + A payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid. + """ + + class RetrieveParams(RequestOptions): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + class SearchParams(RequestOptions): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + limit: NotRequired[int] + """ + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + """ + page: NotRequired[str] + """ + A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results. + """ + query: str + """ + The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for invoices](https://stripe.com/docs/search#query-fields-for-invoices). + """ + + class SendInvoiceParams(RequestOptions): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + class UpcomingLinesParams(RequestOptions): + automatic_tax: NotRequired["Invoice.UpcomingLinesParamsAutomaticTax"] + """ + Settings for automatic tax lookup for this invoice preview. + """ + coupon: NotRequired[str] + """ + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + """ + currency: NotRequired[str] + """ + The currency to preview this invoice in. Defaults to that of `customer` if not specified. + """ + customer: NotRequired[str] + """ + The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + """ + customer_details: NotRequired[ + "Invoice.UpcomingLinesParamsCustomerDetails" + ] + """ + Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.UpcomingLinesParamsDiscount]" + ] + """ + The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts. + """ + ending_before: NotRequired[str] + """ + A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. + """ + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + invoice_items: NotRequired[ + List["Invoice.UpcomingLinesParamsInvoiceItem"] + ] + """ + List of invoice items to add or update in the upcoming invoice preview. + """ + issuer: NotRequired["Invoice.UpcomingLinesParamsIssuer"] + """ + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + """ + limit: NotRequired[int] + """ + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + """ + on_behalf_of: NotRequired["Literal['']|str"] + """ + The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. + """ + schedule: NotRequired[str] + """ + The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. + """ + schedule_details: NotRequired[ + "Invoice.UpcomingLinesParamsScheduleDetails" + ] + """ + The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields. + """ + starting_after: NotRequired[str] + """ + A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. + """ + subscription: NotRequired[str] + """ + The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a `subscription_items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_items` is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions. + """ + subscription_billing_cycle_anchor: NotRequired[ + "Literal['now', 'unchanged']|int" + ] + """ + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. This field has been deprecated and will be removed in a future API version. Use `subscription_details.billing_cycle_anchor` instead. + """ + subscription_cancel_at: NotRequired["Literal['']|int"] + """ + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_at` instead. + """ + subscription_cancel_at_period_end: NotRequired[bool] + """ + Boolean indicating whether this subscription should cancel at the end of the current period. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_at_period_end` instead. + """ + subscription_cancel_now: NotRequired[bool] + """ + This simulates the subscription being canceled or expired immediately. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_now` instead. + """ + subscription_default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. This field has been deprecated and will be removed in a future API version. Use `subscription_details.default_tax_rates` instead. + """ + subscription_details: NotRequired[ + "Invoice.UpcomingLinesParamsSubscriptionDetails" + ] + """ + The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields. + """ + subscription_items: NotRequired[ + List["Invoice.UpcomingLinesParamsSubscriptionItem"] + ] + """ + A list of up to 20 subscription items, each with an attached price. This field has been deprecated and will be removed in a future API version. Use `subscription_details.items` instead. + """ + subscription_proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. This field has been deprecated and will be removed in a future API version. Use `subscription_details.proration_behavior` instead. + """ + subscription_proration_date: NotRequired[int] + """ + If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'. This field has been deprecated and will be removed in a future API version. Use `subscription_details.proration_date` instead. + """ + subscription_resume_at: NotRequired[Literal["now"]] + """ + For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. This field has been deprecated and will be removed in a future API version. Use `subscription_details.resume_at` instead. + """ + subscription_start_date: NotRequired[int] + """ + Date a subscription is intended to start (can be future or past). This field has been deprecated and will be removed in a future API version. Use `subscription_details.start_date` instead. + """ + subscription_trial_end: NotRequired["Literal['now']|int"] + """ + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required. This field has been deprecated and will be removed in a future API version. Use `subscription_details.trial_end` instead. + """ + subscription_trial_from_plan: NotRequired[bool] + """ + Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `subscription_trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more. + """ + + class UpcomingLinesParamsAutomaticTax(TypedDict): + enabled: bool + """ + Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. + """ + liability: NotRequired[ + "Invoice.UpcomingLinesParamsAutomaticTaxLiability" + ] + """ + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. + """ + + class UpcomingLinesParamsAutomaticTaxLiability(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class UpcomingLinesParamsCustomerDetails(TypedDict): + address: NotRequired[ + "Literal['']|Invoice.UpcomingLinesParamsCustomerDetailsAddress" + ] + """ + The customer's address. + """ + shipping: NotRequired[ + "Literal['']|Invoice.UpcomingLinesParamsCustomerDetailsShipping" + ] + """ + The customer's shipping information. Appears on invoices emailed to this customer. + """ + tax: NotRequired["Invoice.UpcomingLinesParamsCustomerDetailsTax"] + """ + Tax details about the customer. + """ + tax_exempt: NotRequired[ + "Literal['']|Literal['exempt', 'none', 'reverse']" + ] + """ + The customer's tax exemption. One of `none`, `exempt`, or `reverse`. + """ + tax_ids: NotRequired[ + List["Invoice.UpcomingLinesParamsCustomerDetailsTaxId"] + ] + """ + The customer's tax IDs. + """ + + class UpcomingLinesParamsCustomerDetailsAddress(TypedDict): + city: NotRequired[str] + """ + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. + """ + + class UpcomingLinesParamsCustomerDetailsShipping(TypedDict): + address: "Invoice.UpcomingLinesParamsCustomerDetailsShippingAddress" + """ + Customer shipping address. + """ + name: str + """ + Customer name. + """ + phone: NotRequired[str] + """ + Customer phone (including extension). + """ + + class UpcomingLinesParamsCustomerDetailsShippingAddress(TypedDict): + city: NotRequired[str] + """ + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. + """ + + class UpcomingLinesParamsCustomerDetailsTax(TypedDict): + ip_address: NotRequired["Literal['']|str"] + """ + A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes. + """ + + class UpcomingLinesParamsCustomerDetailsTaxId(TypedDict): + type: Literal[ + "ad_nrt", + "ae_trn", + "ar_cuit", + "au_abn", + "au_arn", + "bg_uic", + "bh_vat", + "bo_tin", + "br_cnpj", + "br_cpf", + "ca_bn", + "ca_gst_hst", + "ca_pst_bc", + "ca_pst_mb", + "ca_pst_sk", + "ca_qst", + "ch_vat", + "cl_tin", + "cn_tin", + "co_nit", + "cr_tin", + "do_rcn", + "ec_ruc", + "eg_tin", + "es_cif", + "eu_oss_vat", + "eu_vat", + "gb_vat", + "ge_vat", + "hk_br", + "hu_tin", + "id_npwp", + "il_vat", + "in_gst", + "is_vat", + "jp_cn", + "jp_rn", + "jp_trn", + "ke_pin", + "kr_brn", + "kz_bin", + "li_uid", + "mx_rfc", + "my_frp", + "my_itn", + "my_sst", + "ng_tin", + "no_vat", + "no_voec", + "nz_gst", + "om_vat", + "pe_ruc", + "ph_tin", + "ro_tin", + "rs_pib", + "ru_inn", + "ru_kpp", + "sa_vat", + "sg_gst", + "sg_uen", + "si_tin", + "sv_nit", + "th_vat", + "tr_tin", + "tw_vat", + "ua_vat", + "us_ein", + "uy_ruc", + "ve_rif", + "vn_tin", + "za_vat", + ] + """ + Type of the tax ID, one of `ad_nrt`, `ae_trn`, `ar_cuit`, `au_abn`, `au_arn`, `bg_uic`, `bh_vat`, `bo_tin`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_vat`, `cl_tin`, `cn_tin`, `co_nit`, `cr_tin`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `eu_oss_vat`, `eu_vat`, `gb_vat`, `ge_vat`, `hk_br`, `hu_tin`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kr_brn`, `kz_bin`, `li_uid`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sv_nit`, `th_vat`, `tr_tin`, `tw_vat`, `ua_vat`, `us_ein`, `uy_ruc`, `ve_rif`, `vn_tin`, or `za_vat` + """ + value: str + """ + Value of the tax ID. + """ + + class UpcomingLinesParamsDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class UpcomingLinesParamsInvoiceItem(TypedDict): + amount: NotRequired[int] + """ + The integer amount in cents (or local equivalent) of previewed invoice item. + """ + currency: NotRequired[str] + """ + 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). Only applicable to new invoice items. + """ + description: NotRequired[str] + """ + An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + """ + discountable: NotRequired[bool] + """ + Explicitly controls whether discounts apply to this invoice item. Defaults to true, except for negative invoice items. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.UpcomingLinesParamsInvoiceItemDiscount]" + ] + """ + The coupons to redeem into discounts for the invoice item in the preview. + """ + invoiceitem: NotRequired[str] + """ + The ID of the invoice item to update in preview. If not specified, a new invoice item will be added to the preview of the upcoming invoice. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + period: NotRequired["Invoice.UpcomingLinesParamsInvoiceItemPeriod"] + """ + The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "Invoice.UpcomingLinesParamsInvoiceItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Non-negative integer. The quantity of units for the invoice item. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + tax_code: NotRequired["Literal['']|str"] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates that apply to the item. When set, any `default_tax_rates` do not apply to this item. + """ + unit_amount: NotRequired[int] + """ + The integer unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer's account, pass a negative unit_amount. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class UpcomingLinesParamsInvoiceItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class UpcomingLinesParamsInvoiceItemPeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class UpcomingLinesParamsInvoiceItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class UpcomingLinesParamsIssuer(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class UpcomingLinesParamsScheduleDetails(TypedDict): + end_behavior: NotRequired[Literal["cancel", "release"]] + """ + Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running. `cancel` will end the subscription schedule and cancel the underlying subscription. + """ + phases: NotRequired[ + List["Invoice.UpcomingLinesParamsScheduleDetailsPhase"] + ] + """ + List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the `end_date` of one phase will always equal the `start_date` of the next phase. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + In cases where the `schedule_details` params update the currently active phase, specifies if and how to prorate at the time of the request. + """ + + class UpcomingLinesParamsScheduleDetailsPhase(TypedDict): + add_invoice_items: NotRequired[ + List[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseAddInvoiceItem" + ] + ] + """ + A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. You may pass up to 20 items. + """ + application_fee_percent: NotRequired[float] + """ + 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 application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions). + """ + automatic_tax: NotRequired[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseAutomaticTax" + ] + """ + Automatic tax settings for this phase. + """ + billing_cycle_anchor: NotRequired[Literal["automatic", "phase_start"]] + """ + Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle). + """ + billing_thresholds: NotRequired[ + "Literal['']|Invoice.UpcomingLinesParamsScheduleDetailsPhaseBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds. + """ + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] + """ + Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically` on creation. + """ + coupon: NotRequired[str] + """ + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + """ + currency: NotRequired[str] + """ + 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). """ - - class MarkUncollectibleParams(RequestOptions): - expand: NotRequired[List[str]] + default_payment_method: NotRequired[str] """ - Specifies which fields in the response should be expanded. + ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer's invoice settings. """ - - class ModifyParams(RequestOptions): - account_tax_ids: NotRequired["Literal['']|List[str]"] + default_tax_rates: NotRequired["Literal['']|List[str]"] """ - The account tax IDs associated with the invoice. Only editable when the invoice is a draft. + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will set the Subscription's [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates), which means they will be the Invoice's [`default_tax_rates`](https://stripe.com/docs/api/invoices/create#create_invoice-default_tax_rates) for any Invoices issued by the Subscription during this Phase. """ - application_fee_amount: NotRequired[int] + description: NotRequired["Literal['']|str"] """ - A fee in cents (or local equivalent) that will be applied to the invoice and transferred to the application owner's Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee. For more information, see the application fees [documentation](https://stripe.com/docs/billing/invoices/connect#collecting-fees). + Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. """ - auto_advance: NotRequired[bool] + discounts: NotRequired[ + "Literal['']|List[Invoice.UpcomingLinesParamsScheduleDetailsPhaseDiscount]" + ] """ - Controls whether Stripe performs [automatic collection](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection) of the invoice. + The coupons to redeem into discounts for the schedule phase. If not specified, inherits the discount from the subscription's customer. Pass an empty string to avoid inheriting any discounts. """ - automatic_tax: NotRequired["Invoice.ModifyParamsAutomaticTax"] + end_date: NotRequired["int|Literal['now']"] """ - Settings for automatic tax lookup for this invoice. + The date at which this phase of the subscription schedule ends. If set, `iterations` must not be set. """ - collection_method: NotRequired[ - Literal["charge_automatically", "send_invoice"] + invoice_settings: NotRequired[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseInvoiceSettings" ] """ - Either `charge_automatically` or `send_invoice`. This field can be updated only on `draft` invoices. + All invoices will be billed using the specified settings. """ - custom_fields: NotRequired[ - "Literal['']|List[Invoice.ModifyParamsCustomField]" - ] + items: List["Invoice.UpcomingLinesParamsScheduleDetailsPhaseItem"] """ - A list of up to 4 custom fields to be displayed on the invoice. If a value for `custom_fields` is specified, the list specified will replace the existing custom field list on this invoice. Pass an empty string to remove previously-defined fields. + List of configuration items, each with an attached price, to apply during this phase of the subscription schedule. """ - days_until_due: NotRequired[int] + iterations: NotRequired[int] """ - The number of days from which the invoice is created until it is due. Only valid for invoices where `collection_method=send_invoice`. This field can only be updated on `draft` invoices. + Integer representing the multiplier applied to the price interval. For example, `iterations=2` applied to a price with `interval=month` and `interval_count=3` results in a phase of duration `2 * 3 months = 6 months`. If set, `end_date` must not be set. """ - default_payment_method: NotRequired[str] + metadata: NotRequired[Dict[str, str]] """ - ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings. + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a phase. Metadata on a schedule's phase will update the underlying subscription's `metadata` when the phase is entered, adding new keys and replacing existing keys in the subscription's `metadata`. Individual keys in the subscription's `metadata` can be unset by posting an empty value to them in the phase's `metadata`. To unset all keys in the subscription's `metadata`, update the subscription directly or unset every key individually from the phase's `metadata`. """ - default_source: NotRequired["Literal['']|str"] + on_behalf_of: NotRequired[str] """ - ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source. + The account on behalf of which to charge, for each of the associated subscription's invoices. """ - default_tax_rates: NotRequired["Literal['']|List[str]"] + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] """ - The tax rates that will apply to any line item that does not have `tax_rates` set. Pass an empty string to remove previously-defined tax rates. + Whether the subscription schedule will create [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when transitioning to this phase. The default value is `create_prorations`. This setting controls prorations when a phase is started asynchronously and it is persisted as a field on the phase. It's different from the request-level [proration_behavior](https://stripe.com/docs/api/subscription_schedules/update#update_subscription_schedule-proration_behavior) parameter which controls what happens if the update request affects the billing configuration of the current phase. """ - description: NotRequired[str] + start_date: NotRequired["int|Literal['now']"] """ - An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard. + The date at which this phase of the subscription schedule starts or `now`. Must be set on the first phase. """ - discounts: NotRequired[ - "Literal['']|List[Invoice.ModifyParamsDiscount]" + transfer_data: NotRequired[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseTransferData" ] """ - The discounts that will apply to the invoice. Pass an empty string to remove previously-defined discounts. + The data with which to automatically create a Transfer for each of the associated subscription's invoices. """ - due_date: NotRequired[int] + trial: NotRequired[bool] """ - The date on which payment for this invoice is due. Only valid for invoices where `collection_method=send_invoice`. This field can only be updated on `draft` invoices. + If set to true the entire phase is counted as a trial and the customer will not be charged for any fees. """ - effective_at: NotRequired["Literal['']|int"] + trial_end: NotRequired["int|Literal['now']"] """ - The date when this invoice is in effect. Same as `finalized_at` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt. + Sets the phase to trialing from the start date to this date. Must be before the phase end date, can not be combined with `trial` """ - expand: NotRequired[List[str]] + + class UpcomingLinesParamsScheduleDetailsPhaseAddInvoiceItem(TypedDict): + discounts: NotRequired[ + List[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseAddInvoiceItemDiscount" + ] + ] """ - Specifies which fields in the response should be expanded. + The coupons to redeem into discounts for the item. """ - footer: NotRequired[str] + price: NotRequired[str] """ - Footer to be displayed on the invoice. + The ID of the price object. """ - issuer: NotRequired["Invoice.ModifyParamsIssuer"] + price_data: NotRequired[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseAddInvoiceItemPriceData" + ] """ - The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ - metadata: NotRequired["Literal['']|Dict[str, str]"] + quantity: NotRequired[int] """ - 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + Quantity for this item. Defaults to 1. """ - number: NotRequired["Literal['']|str"] + tax_rates: NotRequired["Literal['']|List[str]"] """ - Set the number for this invoice. If no number is present then a number will be assigned automatically when the invoice is finalized. In many markets, regulations require invoices to be unique, sequential and / or gapless. You are responsible for ensuring this is true across all your different invoicing systems in the event that you edit the invoice number using our API. If you use only Stripe for your invoices and do not change invoice numbers, Stripe handles this aspect of compliance for you automatically. + The tax rates which apply to the item. When set, the `default_tax_rates` do not apply to this item. """ - on_behalf_of: NotRequired["Literal['']|str"] + + class UpcomingLinesParamsScheduleDetailsPhaseAddInvoiceItemDiscount( + TypedDict, + ): + coupon: NotRequired[str] """ - The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. + ID of the coupon to create a new discount for. """ - payment_settings: NotRequired["Invoice.ModifyParamsPaymentSettings"] + discount: NotRequired[str] """ - Configuration settings for the PaymentIntent that is generated when the invoice is finalized. + ID of an existing discount on the object (or one of its ancestors) to reuse. """ - rendering: NotRequired["Invoice.ModifyParamsRendering"] + promotion_code: NotRequired[str] """ - The rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page. + ID of the promotion code to create a new discount for. """ - shipping_cost: NotRequired[ - "Literal['']|Invoice.ModifyParamsShippingCost" - ] + + class UpcomingLinesParamsScheduleDetailsPhaseAddInvoiceItemPriceData( + TypedDict, + ): + currency: str """ - Settings for the cost of shipping for this invoice. + 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). """ - shipping_details: NotRequired[ - "Literal['']|Invoice.ModifyParamsShippingDetails" + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] ] """ - Shipping details for the invoice. The Invoice PDF will use the `shipping_details` value if it is set, otherwise the PDF will render the shipping address from the customer. + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. """ - statement_descriptor: NotRequired[str] + unit_amount: NotRequired[int] """ - Extra information about a charge for the customer's credit card statement. It must contain at least one letter. If not specified and this invoice is part of a subscription, the default `statement_descriptor` will be set to the first subscription item's product's `statement_descriptor`. + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. """ - transfer_data: NotRequired[ - "Literal['']|Invoice.ModifyParamsTransferData" - ] + unit_amount_decimal: NotRequired[str] """ - If specified, the funds from the invoice will be transferred to the destination and the ID of the resulting transfer will be found on the invoice's charge. This will be unset if you POST an empty value. + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - class ModifyParamsAutomaticTax(TypedDict): + class UpcomingLinesParamsScheduleDetailsPhaseAutomaticTax(TypedDict): enabled: bool """ - Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. + Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription. """ - liability: NotRequired["Invoice.ModifyParamsAutomaticTaxLiability"] + liability: NotRequired[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseAutomaticTaxLiability" + ] """ The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. """ - class ModifyParamsAutomaticTaxLiability(TypedDict): + class UpcomingLinesParamsScheduleDetailsPhaseAutomaticTaxLiability( + TypedDict, + ): account: NotRequired[str] """ The connected account being referenced when `type` is `account`. @@ -1826,17 +4005,17 @@ class ModifyParamsAutomaticTaxLiability(TypedDict): Type of the account referenced in the request. """ - class ModifyParamsCustomField(TypedDict): - name: str + class UpcomingLinesParamsScheduleDetailsPhaseBillingThresholds(TypedDict): + amount_gte: NotRequired[int] """ - The name of the custom field. This may be up to 40 characters. + Monetary threshold that triggers the subscription to advance to a new billing period """ - value: str + reset_billing_cycle_anchor: NotRequired[bool] """ - The value of the custom field. This may be up to 140 characters. + Indicates if the `billing_cycle_anchor` should be reset when a threshold is reached. If true, `billing_cycle_anchor` will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged. """ - class ModifyParamsDiscount(TypedDict): + class UpcomingLinesParamsScheduleDetailsPhaseDiscount(TypedDict): coupon: NotRequired[str] """ ID of the coupon to create a new discount for. @@ -1850,485 +4029,422 @@ class ModifyParamsDiscount(TypedDict): ID of the promotion code to create a new discount for. """ - class ModifyParamsIssuer(TypedDict): - account: NotRequired[str] - """ - The connected account being referenced when `type` is `account`. - """ - type: Literal["account", "self"] + class UpcomingLinesParamsScheduleDetailsPhaseInvoiceSettings(TypedDict): + account_tax_ids: NotRequired["Literal['']|List[str]"] """ - Type of the account referenced in the request. + 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. """ - - class ModifyParamsPaymentSettings(TypedDict): - default_mandate: NotRequired["Literal['']|str"] + days_until_due: NotRequired[int] """ - ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the invoice's default_payment_method or default_source, if set. + Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be `null` for subscription schedules where `billing=charge_automatically`. """ - payment_method_options: NotRequired[ - "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptions" + issuer: NotRequired[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseInvoiceSettingsIssuer" ] """ - Payment-method-specific configuration to provide to the invoice's PaymentIntent. + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. """ - payment_method_types: NotRequired[ - "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'sepa_credit_transfer', 'sepa_debit', 'sofort', 'us_bank_account', 'wechat_pay']]" - ] + + class UpcomingLinesParamsScheduleDetailsPhaseInvoiceSettingsIssuer( + TypedDict, + ): + account: NotRequired[str] """ - The list of payment method types (e.g. card) to provide to the invoice's PaymentIntent. If not set, Stripe attempts to automatically determine the types to use by looking at the invoice's default payment method, the subscription's default payment method, the customer's default payment method, and your [invoice template settings](https://dashboard.stripe.com/settings/billing/invoice). + The connected account being referenced when `type` is `account`. """ - - class ModifyParamsPaymentSettingsPaymentMethodOptions(TypedDict): - acss_debit: NotRequired[ - "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsAcssDebit" - ] + type: Literal["account", "self"] """ - If paying by `acss_debit`, this sub-hash contains details about the Canadian pre-authorized debit payment method options to pass to the invoice's PaymentIntent. + Type of the account referenced in the request. """ - bancontact: NotRequired[ - "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsBancontact" + + class UpcomingLinesParamsScheduleDetailsPhaseItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|Invoice.UpcomingLinesParamsScheduleDetailsPhaseItemBillingThresholds" ] """ - If paying by `bancontact`, this sub-hash contains details about the Bancontact payment method options to pass to the invoice's PaymentIntent. + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. """ - card: NotRequired[ - "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCard" + discounts: NotRequired[ + "Literal['']|List[Invoice.UpcomingLinesParamsScheduleDetailsPhaseItemDiscount]" ] """ - If paying by `card`, this sub-hash contains details about the Card payment method options to pass to the invoice's PaymentIntent. + The coupons to redeem into discounts for the subscription item. """ - customer_balance: NotRequired[ - "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalance" - ] + metadata: NotRequired[Dict[str, str]] """ - If paying by `customer_balance`, this sub-hash contains details about the Bank transfer payment method options to pass to the invoice's PaymentIntent. + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a configuration item. Metadata on a configuration item will update the underlying subscription item's `metadata` when the phase is entered, adding new keys and replacing existing keys. Individual keys in the subscription item's `metadata` can be unset by posting an empty value to them in the configuration item's `metadata`. To unset all keys in the subscription item's `metadata`, update the subscription item directly or unset every key individually from the configuration item's `metadata`. """ - konbini: NotRequired[ - "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsKonbini" - ] + plan: NotRequired[str] """ - If paying by `konbini`, this sub-hash contains details about the Konbini payment method options to pass to the invoice's PaymentIntent. + The plan ID to subscribe to. You may specify the same ID in `plan` and `price`. """ - sepa_debit: NotRequired[ - "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsSepaDebit" - ] + price: NotRequired[str] """ - If paying by `sepa_debit`, this sub-hash contains details about the SEPA Direct Debit payment method options to pass to the invoice's PaymentIntent. + The ID of the price object. """ - us_bank_account: NotRequired[ - "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsUsBankAccount" + price_data: NotRequired[ + "Invoice.UpcomingLinesParamsScheduleDetailsPhaseItemPriceData" ] """ - If paying by `us_bank_account`, this sub-hash contains details about the ACH direct debit payment method options to pass to the invoice's PaymentIntent. + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ - - class ModifyParamsPaymentSettingsPaymentMethodOptionsAcssDebit(TypedDict): - mandate_options: NotRequired[ - "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsAcssDebitMandateOptions" - ] + quantity: NotRequired[int] """ - Additional fields for Mandate creation + Quantity for the given price. Can be set only if the price's `usage_type` is `licensed` and not `metered`. """ - verification_method: NotRequired[ - Literal["automatic", "instant", "microdeposits"] - ] + tax_rates: NotRequired["Literal['']|List[str]"] """ - Verification method for the intent + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. """ - class ModifyParamsPaymentSettingsPaymentMethodOptionsAcssDebitMandateOptions( + class UpcomingLinesParamsScheduleDetailsPhaseItemBillingThresholds( TypedDict, ): - transaction_type: NotRequired[Literal["business", "personal"]] + usage_gte: int """ - Transaction type of the mandate. + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) """ - class ModifyParamsPaymentSettingsPaymentMethodOptionsBancontact(TypedDict): - preferred_language: NotRequired[Literal["de", "en", "fr", "nl"]] + class UpcomingLinesParamsScheduleDetailsPhaseItemDiscount(TypedDict): + coupon: NotRequired[str] """ - Preferred language of the Bancontact authorization page that the customer is redirected to. + ID of the coupon to create a new discount for. """ - - class ModifyParamsPaymentSettingsPaymentMethodOptionsCard(TypedDict): - installments: NotRequired[ - "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCardInstallments" - ] + discount: NotRequired[str] """ - Installment configuration for payments attempted on this invoice (Mexico Only). - - For more information, see the [installments integration guide](https://stripe.com/docs/payments/installments). + ID of an existing discount on the object (or one of its ancestors) to reuse. """ - request_three_d_secure: NotRequired[ - Literal["any", "automatic", "challenge"] - ] + promotion_code: NotRequired[str] """ - 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. + ID of the promotion code to create a new discount for. """ - class ModifyParamsPaymentSettingsPaymentMethodOptionsCardInstallments( - TypedDict, - ): - enabled: NotRequired[bool] + class UpcomingLinesParamsScheduleDetailsPhaseItemPriceData(TypedDict): + currency: str """ - Setting to true enables installments for this invoice. - Setting to false will prevent any selected plan from applying to a payment. + 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). """ - plan: NotRequired[ - "Literal['']|Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCardInstallmentsPlan" - ] + product: str """ - The selected installment plan to use for this invoice. + The ID of the product that this price will belong to. """ - - class ModifyParamsPaymentSettingsPaymentMethodOptionsCardInstallmentsPlan( - TypedDict, - ): - count: int + recurring: "Invoice.UpcomingLinesParamsScheduleDetailsPhaseItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] """ - For `fixed_count` installment plans, this is the number of installment payments your customer will make to their credit card. + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. """ - interval: Literal["month"] + unit_amount: NotRequired[int] """ - For `fixed_count` installment plans, this is the interval between installment payments your customer will make to their credit card. - One of `month`. + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. """ - type: Literal["fixed_count"] + unit_amount_decimal: NotRequired[str] """ - Type of installment plan, one of `fixed_count`. + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - class ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalance( + class UpcomingLinesParamsScheduleDetailsPhaseItemPriceDataRecurring( TypedDict, ): - bank_transfer: NotRequired[ - "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalanceBankTransfer" - ] + interval: Literal["day", "month", "week", "year"] """ - Configuration for the bank transfer funding type, if the `funding_type` is set to `bank_transfer`. + Specifies billing frequency. Either `day`, `week`, `month` or `year`. """ - funding_type: NotRequired[str] + interval_count: NotRequired[int] """ - The funding method type to be used when there are not enough funds in the customer balance. Permitted values include: `bank_transfer`. + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ - class ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalanceBankTransfer( - TypedDict, - ): - eu_bank_transfer: NotRequired[ - "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalanceBankTransferEuBankTransfer" - ] + class UpcomingLinesParamsScheduleDetailsPhaseTransferData(TypedDict): + amount_percent: NotRequired[float] """ - Configuration for eu_bank_transfer funding type. + 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. """ - type: NotRequired[str] + destination: str """ - The bank transfer type that can be used for funding. Permitted values include: `eu_bank_transfer`, `gb_bank_transfer`, `jp_bank_transfer`, `mx_bank_transfer`, or `us_bank_transfer`. + ID of an existing, connected Stripe account. """ - class ModifyParamsPaymentSettingsPaymentMethodOptionsCustomerBalanceBankTransferEuBankTransfer( - TypedDict, - ): - country: str + class UpcomingLinesParamsSubscriptionDetails(TypedDict): + billing_cycle_anchor: NotRequired["Literal['now', 'unchanged']|int"] """ - The desired country code of the bank account information. Permitted values include: `BE`, `DE`, `ES`, `FR`, `IE`, or `NL`. + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. """ - - class ModifyParamsPaymentSettingsPaymentMethodOptionsKonbini(TypedDict): - pass - - class ModifyParamsPaymentSettingsPaymentMethodOptionsSepaDebit(TypedDict): - pass - - class ModifyParamsPaymentSettingsPaymentMethodOptionsUsBankAccount( - TypedDict, - ): - financial_connections: NotRequired[ - "Invoice.ModifyParamsPaymentSettingsPaymentMethodOptionsUsBankAccountFinancialConnections" - ] + cancel_at: NotRequired["Literal['']|int"] """ - Additional fields for Financial Connections Session creation + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. """ - verification_method: NotRequired[ - Literal["automatic", "instant", "microdeposits"] - ] + cancel_at_period_end: NotRequired[bool] """ - Verification method for the intent + Boolean indicating whether this subscription should cancel at the end of the current period. """ - - class ModifyParamsPaymentSettingsPaymentMethodOptionsUsBankAccountFinancialConnections( - TypedDict, - ): - permissions: NotRequired[ - List[ - Literal[ - "balances", "ownership", "payment_method", "transactions" - ] - ] - ] + cancel_now: NotRequired[bool] """ - The list of permissions to request. If this parameter is passed, the `payment_method` permission must be included. Valid permissions include: `balances`, `ownership`, `payment_method`, and `transactions`. + This simulates the subscription being canceled or expired immediately. """ - prefetch: NotRequired[ - List[Literal["balances", "ownership", "transactions"]] + default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. + """ + items: NotRequired[ + List["Invoice.UpcomingLinesParamsSubscriptionDetailsItem"] ] """ - List of data features that you would like to retrieve upon account creation. + A list of up to 20 subscription items, each with an attached price. """ - - class ModifyParamsRendering(TypedDict): - amount_tax_display: NotRequired[ - "Literal['']|Literal['exclude_tax', 'include_inclusive_tax']" + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] ] """ - How line-item prices and amounts will be displayed with respect to tax on invoice PDFs. One of `exclude_tax` or `include_inclusive_tax`. `include_inclusive_tax` will include inclusive tax (and exclude exclusive tax) in invoice PDF amounts. `exclude_tax` will exclude all tax (inclusive and exclusive alike) from invoice PDF amounts. + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. """ - pdf: NotRequired["Invoice.ModifyParamsRenderingPdf"] + proration_date: NotRequired[int] """ - Invoice pdf rendering options + If previewing an update to a subscription, and doing proration, `subscription_details.proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_details.items`, or `subscription_details.trial_end` are required. Also, `subscription_details.proration_behavior` cannot be set to 'none'. """ - - class ModifyParamsRenderingPdf(TypedDict): - page_size: NotRequired[Literal["a4", "auto", "letter"]] + resume_at: NotRequired[Literal["now"]] """ - Page size for invoice PDF. Can be set to `a4`, `letter`, or `auto`. - If set to `auto`, invoice PDF page size defaults to `a4` for customers with - Japanese locale and `letter` for customers with other locales. + For paused subscriptions, setting `subscription_details.resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. """ - - class ModifyParamsShippingCost(TypedDict): - shipping_rate: NotRequired[str] + start_date: NotRequired[int] """ - The ID of the shipping rate to use for this order. + Date a subscription is intended to start (can be future or past). """ - shipping_rate_data: NotRequired[ - "Invoice.ModifyParamsShippingCostShippingRateData" - ] + trial_end: NotRequired["Literal['now']|int"] """ - Parameters to create a new ad-hoc shipping rate for this order. + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_details.items` or `subscription` is required. """ - class ModifyParamsShippingCostShippingRateData(TypedDict): - delivery_estimate: NotRequired[ - "Invoice.ModifyParamsShippingCostShippingRateDataDeliveryEstimate" + class UpcomingLinesParamsSubscriptionDetailsItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|Invoice.UpcomingLinesParamsSubscriptionDetailsItemBillingThresholds" ] """ - The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions. + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. """ - display_name: str + clear_usage: NotRequired[bool] """ - The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions. + Delete all usage for a given subscription item. Allowed only when `deleted` is set to `true` and the current plan's `usage_type` is `metered`. """ - fixed_amount: NotRequired[ - "Invoice.ModifyParamsShippingCostShippingRateDataFixedAmount" - ] + deleted: NotRequired[bool] """ - Describes a fixed amount to charge for shipping. Must be present if type is `fixed_amount`. + A flag that, if set to `true`, will delete the specified item. """ - metadata: NotRequired[Dict[str, str]] + discounts: NotRequired[ + "Literal['']|List[Invoice.UpcomingLinesParamsSubscriptionDetailsItemDiscount]" + ] """ - 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + The coupons to redeem into discounts for the subscription item. """ - tax_behavior: NotRequired[ - Literal["exclusive", "inclusive", "unspecified"] - ] + id: NotRequired[str] """ - Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. + Subscription item to update. """ - tax_code: NotRequired[str] + metadata: NotRequired["Literal['']|Dict[str, str]"] """ - A [tax code](https://stripe.com/docs/tax/tax-categories) ID. The Shipping tax code is `txcd_92010001`. + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. """ - type: NotRequired[Literal["fixed_amount"]] + plan: NotRequired[str] """ - The type of calculation to use on the shipping rate. Can only be `fixed_amount` for now. + Plan ID for this item, as a string. """ - - class ModifyParamsShippingCostShippingRateDataDeliveryEstimate(TypedDict): - maximum: NotRequired[ - "Invoice.ModifyParamsShippingCostShippingRateDataDeliveryEstimateMaximum" - ] + price: NotRequired[str] """ - The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite. + The ID of the price object. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided. """ - minimum: NotRequired[ - "Invoice.ModifyParamsShippingCostShippingRateDataDeliveryEstimateMinimum" + price_data: NotRequired[ + "Invoice.UpcomingLinesParamsSubscriptionDetailsItemPriceData" ] """ - The lower bound of the estimated range. If empty, represents no lower bound. + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ - - class ModifyParamsShippingCostShippingRateDataDeliveryEstimateMaximum( - TypedDict, - ): - unit: Literal["business_day", "day", "hour", "month", "week"] + quantity: NotRequired[int] """ - A unit of time. + Quantity for this item. """ - value: int + tax_rates: NotRequired["Literal['']|List[str]"] """ - Must be greater than 0. + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. """ - class ModifyParamsShippingCostShippingRateDataDeliveryEstimateMinimum( + class UpcomingLinesParamsSubscriptionDetailsItemBillingThresholds( TypedDict, ): - unit: Literal["business_day", "day", "hour", "month", "week"] + usage_gte: int """ - A unit of time. + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) """ - value: int + + class UpcomingLinesParamsSubscriptionDetailsItemDiscount(TypedDict): + coupon: NotRequired[str] """ - Must be greater than 0. + ID of the coupon to create a new discount for. """ - - class ModifyParamsShippingCostShippingRateDataFixedAmount(TypedDict): - amount: int + discount: NotRequired[str] """ - A non-negative integer in cents representing how much to charge. + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. """ + + class UpcomingLinesParamsSubscriptionDetailsItemPriceData(TypedDict): currency: str """ 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_options: NotRequired[ - Dict[ - str, - "Invoice.ModifyParamsShippingCostShippingRateDataFixedAmountCurrencyOptions", - ] + product: str + """ + The ID of the product that this price will belong to. + """ + recurring: "Invoice.UpcomingLinesParamsSubscriptionDetailsItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] ] """ - Shipping rates defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies). + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - class ModifyParamsShippingCostShippingRateDataFixedAmountCurrencyOptions( + class UpcomingLinesParamsSubscriptionDetailsItemPriceDataRecurring( TypedDict, ): - amount: int + interval: Literal["day", "month", "week", "year"] """ - A non-negative integer in cents representing how much to charge. + Specifies billing frequency. Either `day`, `week`, `month` or `year`. """ - tax_behavior: NotRequired[ - Literal["exclusive", "inclusive", "unspecified"] - ] + interval_count: NotRequired[int] """ - Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ - class ModifyParamsShippingDetails(TypedDict): - address: "Invoice.ModifyParamsShippingDetailsAddress" + class UpcomingLinesParamsSubscriptionItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|Invoice.UpcomingLinesParamsSubscriptionItemBillingThresholds" + ] """ - Shipping address + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. """ - name: str + clear_usage: NotRequired[bool] """ - Recipient name. + Delete all usage for a given subscription item. Allowed only when `deleted` is set to `true` and the current plan's `usage_type` is `metered`. """ - phone: NotRequired["Literal['']|str"] + deleted: NotRequired[bool] """ - Recipient phone (including extension) + A flag that, if set to `true`, will delete the specified item. """ - - class ModifyParamsShippingDetailsAddress(TypedDict): - city: NotRequired[str] + discounts: NotRequired[ + "Literal['']|List[Invoice.UpcomingLinesParamsSubscriptionItemDiscount]" + ] """ - City, district, suburb, town, or village. + The coupons to redeem into discounts for the subscription item. """ - country: NotRequired[str] + id: NotRequired[str] """ - Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + Subscription item to update. """ - line1: NotRequired[str] + metadata: NotRequired["Literal['']|Dict[str, str]"] """ - Address line 1 (e.g., street, PO Box, or company name). + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. """ - line2: NotRequired[str] + plan: NotRequired[str] """ - Address line 2 (e.g., apartment, suite, unit, or building). + Plan ID for this item, as a string. """ - postal_code: NotRequired[str] + price: NotRequired[str] """ - ZIP or postal code. + The ID of the price object. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided. """ - state: NotRequired[str] + price_data: NotRequired[ + "Invoice.UpcomingLinesParamsSubscriptionItemPriceData" + ] """ - State, county, province, or region. + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ - - class ModifyParamsTransferData(TypedDict): - amount: NotRequired[int] + quantity: NotRequired[int] """ - The amount that will be transferred automatically when the invoice is paid. If no amount is set, the full amount is transferred. + Quantity for this item. """ - destination: str + tax_rates: NotRequired["Literal['']|List[str]"] """ - ID of an existing, connected Stripe account. + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. """ - class PayParams(RequestOptions): - expand: NotRequired[List[str]] - """ - Specifies which fields in the response should be expanded. + class UpcomingLinesParamsSubscriptionItemBillingThresholds(TypedDict): + usage_gte: int """ - forgive: NotRequired[bool] + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) """ - In cases where the source used to pay the invoice has insufficient funds, passing `forgive=true` controls whether a charge should be attempted for the full amount available on the source, up to the amount to fully pay the invoice. This effectively forgives the difference between the amount available on the source and the amount due. - Passing `forgive=false` will fail the charge if the source hasn't been pre-funded with the right amount. An example for this case is with ACH Credit Transfers and wires: if the amount wired is less than the amount due by a small amount, you might want to forgive the difference. Defaults to `false`. - """ - mandate: NotRequired["Literal['']|str"] + class UpcomingLinesParamsSubscriptionItemDiscount(TypedDict): + coupon: NotRequired[str] """ - ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the payment_method param or the invoice's default_payment_method or default_source, if set. + ID of the coupon to create a new discount for. """ - off_session: NotRequired[bool] + discount: NotRequired[str] """ - Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `true` (off-session). + ID of an existing discount on the object (or one of its ancestors) to reuse. """ - paid_out_of_band: NotRequired[bool] + promotion_code: NotRequired[str] """ - Boolean representing whether an invoice is paid outside of Stripe. This will result in no charge being made. Defaults to `false`. + ID of the promotion code to create a new discount for. """ - payment_method: NotRequired[str] + + class UpcomingLinesParamsSubscriptionItemPriceData(TypedDict): + currency: str """ - A PaymentMethod to be charged. The PaymentMethod must be the ID of a PaymentMethod belonging to the customer associated with the invoice being paid. + 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). """ - source: NotRequired[str] + product: str """ - A payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid. + The ID of the product that this price will belong to. """ - - class RetrieveParams(RequestOptions): - expand: NotRequired[List[str]] + recurring: "Invoice.UpcomingLinesParamsSubscriptionItemPriceDataRecurring" """ - Specifies which fields in the response should be expanded. + The recurring components of a price such as `interval` and `interval_count`. """ - - class SearchParams(RequestOptions): - expand: NotRequired[List[str]] + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] """ - Specifies which fields in the response should be expanded. + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. """ - limit: NotRequired[int] + unit_amount: NotRequired[int] """ - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. """ - page: NotRequired[str] + unit_amount_decimal: NotRequired[str] """ - A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results. + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - query: str + + class UpcomingLinesParamsSubscriptionItemPriceDataRecurring(TypedDict): + interval: Literal["day", "month", "week", "year"] """ - The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for invoices](https://stripe.com/docs/search#query-fields-for-invoices). + Specifies billing frequency. Either `day`, `week`, `month` or `year`. """ - - class SendInvoiceParams(RequestOptions): - expand: NotRequired[List[str]] + interval_count: NotRequired[int] """ - Specifies which fields in the response should be expanded. + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ - class UpcomingLinesParams(RequestOptions): - automatic_tax: NotRequired["Invoice.UpcomingLinesParamsAutomaticTax"] + class UpcomingParams(RequestOptions): + automatic_tax: NotRequired["Invoice.UpcomingParamsAutomaticTax"] """ Settings for automatic tax lookup for this invoice preview. """ @@ -2344,40 +4460,28 @@ class UpcomingLinesParams(RequestOptions): """ The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. """ - customer_details: NotRequired[ - "Invoice.UpcomingLinesParamsCustomerDetails" - ] + customer_details: NotRequired["Invoice.UpcomingParamsCustomerDetails"] """ Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. """ discounts: NotRequired[ - "Literal['']|List[Invoice.UpcomingLinesParamsDiscount]" + "Literal['']|List[Invoice.UpcomingParamsDiscount]" ] """ The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts. """ - ending_before: NotRequired[str] - """ - A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. - """ expand: NotRequired[List[str]] """ Specifies which fields in the response should be expanded. """ - invoice_items: NotRequired[ - List["Invoice.UpcomingLinesParamsInvoiceItem"] - ] + invoice_items: NotRequired[List["Invoice.UpcomingParamsInvoiceItem"]] """ List of invoice items to add or update in the upcoming invoice preview. """ - issuer: NotRequired["Invoice.UpcomingLinesParamsIssuer"] + issuer: NotRequired["Invoice.UpcomingParamsIssuer"] """ The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. """ - limit: NotRequired[int] - """ - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. - """ on_behalf_of: NotRequired["Literal['']|str"] """ The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. @@ -2386,9 +4490,9 @@ class UpcomingLinesParams(RequestOptions): """ The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. """ - starting_after: NotRequired[str] + schedule_details: NotRequired["Invoice.UpcomingParamsScheduleDetails"] """ - A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. + The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields. """ subscription: NotRequired[str] """ @@ -2398,70 +4502,74 @@ class UpcomingLinesParams(RequestOptions): "Literal['now', 'unchanged']|int" ] """ - For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. This field has been deprecated and will be removed in a future API version. Use `subscription_details.billing_cycle_anchor` instead. """ subscription_cancel_at: NotRequired["Literal['']|int"] """ - A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_at` instead. """ subscription_cancel_at_period_end: NotRequired[bool] """ - Boolean indicating whether this subscription should cancel at the end of the current period. + Boolean indicating whether this subscription should cancel at the end of the current period. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_at_period_end` instead. """ subscription_cancel_now: NotRequired[bool] """ - This simulates the subscription being canceled or expired immediately. + This simulates the subscription being canceled or expired immediately. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_now` instead. """ subscription_default_tax_rates: NotRequired["Literal['']|List[str]"] """ - If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. This field has been deprecated and will be removed in a future API version. Use `subscription_details.default_tax_rates` instead. + """ + subscription_details: NotRequired[ + "Invoice.UpcomingParamsSubscriptionDetails" + ] + """ + The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields. """ subscription_items: NotRequired[ - List["Invoice.UpcomingLinesParamsSubscriptionItem"] + List["Invoice.UpcomingParamsSubscriptionItem"] ] """ - A list of up to 20 subscription items, each with an attached price. + A list of up to 20 subscription items, each with an attached price. This field has been deprecated and will be removed in a future API version. Use `subscription_details.items` instead. """ subscription_proration_behavior: NotRequired[ Literal["always_invoice", "create_prorations", "none"] ] """ - Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. This field has been deprecated and will be removed in a future API version. Use `subscription_details.proration_behavior` instead. """ subscription_proration_date: NotRequired[int] """ - If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'. + If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'. This field has been deprecated and will be removed in a future API version. Use `subscription_details.proration_date` instead. """ subscription_resume_at: NotRequired[Literal["now"]] """ - For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. + For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. This field has been deprecated and will be removed in a future API version. Use `subscription_details.resume_at` instead. """ subscription_start_date: NotRequired[int] """ - Date a subscription is intended to start (can be future or past). + Date a subscription is intended to start (can be future or past). This field has been deprecated and will be removed in a future API version. Use `subscription_details.start_date` instead. """ subscription_trial_end: NotRequired["Literal['now']|int"] """ - If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required. + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required. This field has been deprecated and will be removed in a future API version. Use `subscription_details.trial_end` instead. """ subscription_trial_from_plan: NotRequired[bool] """ Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `subscription_trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more. """ - class UpcomingLinesParamsAutomaticTax(TypedDict): + class UpcomingParamsAutomaticTax(TypedDict): enabled: bool """ Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. """ - liability: NotRequired[ - "Invoice.UpcomingLinesParamsAutomaticTaxLiability" - ] + liability: NotRequired["Invoice.UpcomingParamsAutomaticTaxLiability"] """ The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. """ - class UpcomingLinesParamsAutomaticTaxLiability(TypedDict): + class UpcomingParamsAutomaticTaxLiability(TypedDict): account: NotRequired[str] """ The connected account being referenced when `type` is `account`. @@ -2471,20 +4579,20 @@ class UpcomingLinesParamsAutomaticTaxLiability(TypedDict): Type of the account referenced in the request. """ - class UpcomingLinesParamsCustomerDetails(TypedDict): + class UpcomingParamsCustomerDetails(TypedDict): address: NotRequired[ - "Literal['']|Invoice.UpcomingLinesParamsCustomerDetailsAddress" + "Literal['']|Invoice.UpcomingParamsCustomerDetailsAddress" ] """ The customer's address. """ shipping: NotRequired[ - "Literal['']|Invoice.UpcomingLinesParamsCustomerDetailsShipping" + "Literal['']|Invoice.UpcomingParamsCustomerDetailsShipping" ] """ The customer's shipping information. Appears on invoices emailed to this customer. """ - tax: NotRequired["Invoice.UpcomingLinesParamsCustomerDetailsTax"] + tax: NotRequired["Invoice.UpcomingParamsCustomerDetailsTax"] """ Tax details about the customer. """ @@ -2495,13 +4603,13 @@ class UpcomingLinesParamsCustomerDetails(TypedDict): The customer's tax exemption. One of `none`, `exempt`, or `reverse`. """ tax_ids: NotRequired[ - List["Invoice.UpcomingLinesParamsCustomerDetailsTaxId"] + List["Invoice.UpcomingParamsCustomerDetailsTaxId"] ] """ The customer's tax IDs. """ - class UpcomingLinesParamsCustomerDetailsAddress(TypedDict): + class UpcomingParamsCustomerDetailsAddress(TypedDict): city: NotRequired[str] """ City, district, suburb, town, or village. @@ -2527,8 +4635,8 @@ class UpcomingLinesParamsCustomerDetailsAddress(TypedDict): State, county, province, or region. """ - class UpcomingLinesParamsCustomerDetailsShipping(TypedDict): - address: "Invoice.UpcomingLinesParamsCustomerDetailsShippingAddress" + class UpcomingParamsCustomerDetailsShipping(TypedDict): + address: "Invoice.UpcomingParamsCustomerDetailsShippingAddress" """ Customer shipping address. """ @@ -2541,7 +4649,7 @@ class UpcomingLinesParamsCustomerDetailsShipping(TypedDict): Customer phone (including extension). """ - class UpcomingLinesParamsCustomerDetailsShippingAddress(TypedDict): + class UpcomingParamsCustomerDetailsShippingAddress(TypedDict): city: NotRequired[str] """ City, district, suburb, town, or village. @@ -2567,13 +4675,13 @@ class UpcomingLinesParamsCustomerDetailsShippingAddress(TypedDict): State, county, province, or region. """ - class UpcomingLinesParamsCustomerDetailsTax(TypedDict): + class UpcomingParamsCustomerDetailsTax(TypedDict): ip_address: NotRequired["Literal['']|str"] """ A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes. """ - class UpcomingLinesParamsCustomerDetailsTaxId(TypedDict): + class UpcomingParamsCustomerDetailsTaxId(TypedDict): type: Literal[ "ad_nrt", "ae_trn", @@ -2655,7 +4763,7 @@ class UpcomingLinesParamsCustomerDetailsTaxId(TypedDict): Value of the tax ID. """ - class UpcomingLinesParamsDiscount(TypedDict): + class UpcomingParamsDiscount(TypedDict): coupon: NotRequired[str] """ ID of the coupon to create a new discount for. @@ -2669,7 +4777,7 @@ class UpcomingLinesParamsDiscount(TypedDict): ID of the promotion code to create a new discount for. """ - class UpcomingLinesParamsInvoiceItem(TypedDict): + class UpcomingParamsInvoiceItem(TypedDict): amount: NotRequired[int] """ The integer amount in cents (or local equivalent) of previewed invoice item. @@ -2687,7 +4795,7 @@ class UpcomingLinesParamsInvoiceItem(TypedDict): Explicitly controls whether discounts apply to this invoice item. Defaults to true, except for negative invoice items. """ discounts: NotRequired[ - "Literal['']|List[Invoice.UpcomingLinesParamsInvoiceItemDiscount]" + "Literal['']|List[Invoice.UpcomingParamsInvoiceItemDiscount]" ] """ The coupons to redeem into discounts for the invoice item in the preview. @@ -2700,7 +4808,7 @@ class UpcomingLinesParamsInvoiceItem(TypedDict): """ 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. """ - period: NotRequired["Invoice.UpcomingLinesParamsInvoiceItemPeriod"] + period: NotRequired["Invoice.UpcomingParamsInvoiceItemPeriod"] """ The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. """ @@ -2708,9 +4816,7 @@ class UpcomingLinesParamsInvoiceItem(TypedDict): """ The ID of the price object. """ - price_data: NotRequired[ - "Invoice.UpcomingLinesParamsInvoiceItemPriceData" - ] + price_data: NotRequired["Invoice.UpcomingParamsInvoiceItemPriceData"] """ Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ @@ -2736,128 +4842,224 @@ class UpcomingLinesParamsInvoiceItem(TypedDict): """ The integer unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer's account, pass a negative unit_amount. """ - unit_amount_decimal: NotRequired[str] + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class UpcomingParamsInvoiceItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class UpcomingParamsInvoiceItemPeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class UpcomingParamsInvoiceItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class UpcomingParamsIssuer(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class UpcomingParamsScheduleDetails(TypedDict): + end_behavior: NotRequired[Literal["cancel", "release"]] + """ + Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running. `cancel` will end the subscription schedule and cancel the underlying subscription. + """ + phases: NotRequired[List["Invoice.UpcomingParamsScheduleDetailsPhase"]] + """ + List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the `end_date` of one phase will always equal the `start_date` of the next phase. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + In cases where the `schedule_details` params update the currently active phase, specifies if and how to prorate at the time of the request. + """ + + class UpcomingParamsScheduleDetailsPhase(TypedDict): + add_invoice_items: NotRequired[ + List["Invoice.UpcomingParamsScheduleDetailsPhaseAddInvoiceItem"] + ] + """ + A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. You may pass up to 20 items. + """ + application_fee_percent: NotRequired[float] + """ + 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 application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions). + """ + automatic_tax: NotRequired[ + "Invoice.UpcomingParamsScheduleDetailsPhaseAutomaticTax" + ] + """ + Automatic tax settings for this phase. + """ + billing_cycle_anchor: NotRequired[Literal["automatic", "phase_start"]] + """ + Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle). + """ + billing_thresholds: NotRequired[ + "Literal['']|Invoice.UpcomingParamsScheduleDetailsPhaseBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds. + """ + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] """ - Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically` on creation. """ - - class UpcomingLinesParamsInvoiceItemDiscount(TypedDict): coupon: NotRequired[str] """ - ID of the coupon to create a new discount for. + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. """ - discount: NotRequired[str] + currency: NotRequired[str] """ - ID of an existing discount on the object (or one of its ancestors) to reuse. + 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). """ - promotion_code: NotRequired[str] + default_payment_method: NotRequired[str] """ - ID of the promotion code to create a new discount for. + ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer's invoice settings. """ - - class UpcomingLinesParamsInvoiceItemPeriod(TypedDict): - end: int + default_tax_rates: NotRequired["Literal['']|List[str]"] """ - The end of the period, which must be greater than or equal to the start. This value is inclusive. + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will set the Subscription's [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates), which means they will be the Invoice's [`default_tax_rates`](https://stripe.com/docs/api/invoices/create#create_invoice-default_tax_rates) for any Invoices issued by the Subscription during this Phase. """ - start: int + description: NotRequired["Literal['']|str"] """ - The start of the period. This value is inclusive. + Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. """ - - class UpcomingLinesParamsInvoiceItemPriceData(TypedDict): - currency: str + discounts: NotRequired[ + "Literal['']|List[Invoice.UpcomingParamsScheduleDetailsPhaseDiscount]" + ] """ - 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). + The coupons to redeem into discounts for the schedule phase. If not specified, inherits the discount from the subscription's customer. Pass an empty string to avoid inheriting any discounts. """ - product: str + end_date: NotRequired["int|Literal['now']"] """ - The ID of the product that this price will belong to. + The date at which this phase of the subscription schedule ends. If set, `iterations` must not be set. """ - tax_behavior: NotRequired[ - Literal["exclusive", "inclusive", "unspecified"] + invoice_settings: NotRequired[ + "Invoice.UpcomingParamsScheduleDetailsPhaseInvoiceSettings" ] """ - Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + All invoices will be billed using the specified settings. """ - unit_amount: NotRequired[int] + items: List["Invoice.UpcomingParamsScheduleDetailsPhaseItem"] """ - A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + List of configuration items, each with an attached price, to apply during this phase of the subscription schedule. """ - unit_amount_decimal: NotRequired[str] + iterations: NotRequired[int] """ - Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + Integer representing the multiplier applied to the price interval. For example, `iterations=2` applied to a price with `interval=month` and `interval_count=3` results in a phase of duration `2 * 3 months = 6 months`. If set, `end_date` must not be set. """ - - class UpcomingLinesParamsIssuer(TypedDict): - account: NotRequired[str] + metadata: NotRequired[Dict[str, str]] """ - The connected account being referenced when `type` is `account`. + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a phase. Metadata on a schedule's phase will update the underlying subscription's `metadata` when the phase is entered, adding new keys and replacing existing keys in the subscription's `metadata`. Individual keys in the subscription's `metadata` can be unset by posting an empty value to them in the phase's `metadata`. To unset all keys in the subscription's `metadata`, update the subscription directly or unset every key individually from the phase's `metadata`. """ - type: Literal["account", "self"] + on_behalf_of: NotRequired[str] """ - Type of the account referenced in the request. + The account on behalf of which to charge, for each of the associated subscription's invoices. """ - - class UpcomingLinesParamsSubscriptionItem(TypedDict): - billing_thresholds: NotRequired[ - "Literal['']|Invoice.UpcomingLinesParamsSubscriptionItemBillingThresholds" + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] ] """ - Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. - """ - clear_usage: NotRequired[bool] - """ - Delete all usage for a given subscription item. Allowed only when `deleted` is set to `true` and the current plan's `usage_type` is `metered`. + Whether the subscription schedule will create [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when transitioning to this phase. The default value is `create_prorations`. This setting controls prorations when a phase is started asynchronously and it is persisted as a field on the phase. It's different from the request-level [proration_behavior](https://stripe.com/docs/api/subscription_schedules/update#update_subscription_schedule-proration_behavior) parameter which controls what happens if the update request affects the billing configuration of the current phase. """ - deleted: NotRequired[bool] + start_date: NotRequired["int|Literal['now']"] """ - A flag that, if set to `true`, will delete the specified item. + The date at which this phase of the subscription schedule starts or `now`. Must be set on the first phase. """ - discounts: NotRequired[ - "Literal['']|List[Invoice.UpcomingLinesParamsSubscriptionItemDiscount]" + transfer_data: NotRequired[ + "Invoice.UpcomingParamsScheduleDetailsPhaseTransferData" ] """ - The coupons to redeem into discounts for the subscription item. + The data with which to automatically create a Transfer for each of the associated subscription's invoices. """ - id: NotRequired[str] + trial: NotRequired[bool] """ - Subscription item to update. + If set to true the entire phase is counted as a trial and the customer will not be charged for any fees. """ - metadata: NotRequired["Literal['']|Dict[str, str]"] + trial_end: NotRequired["int|Literal['now']"] """ - 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + Sets the phase to trialing from the start date to this date. Must be before the phase end date, can not be combined with `trial` """ - plan: NotRequired[str] + + class UpcomingParamsScheduleDetailsPhaseAddInvoiceItem(TypedDict): + discounts: NotRequired[ + List[ + "Invoice.UpcomingParamsScheduleDetailsPhaseAddInvoiceItemDiscount" + ] + ] """ - Plan ID for this item, as a string. + The coupons to redeem into discounts for the item. """ price: NotRequired[str] """ - The ID of the price object. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided. + The ID of the price object. """ price_data: NotRequired[ - "Invoice.UpcomingLinesParamsSubscriptionItemPriceData" + "Invoice.UpcomingParamsScheduleDetailsPhaseAddInvoiceItemPriceData" ] """ Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ quantity: NotRequired[int] """ - Quantity for this item. + Quantity for this item. Defaults to 1. """ tax_rates: NotRequired["Literal['']|List[str]"] """ - A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. - """ - - class UpcomingLinesParamsSubscriptionItemBillingThresholds(TypedDict): - usage_gte: int - """ - Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) + The tax rates which apply to the item. When set, the `default_tax_rates` do not apply to this item. """ - class UpcomingLinesParamsSubscriptionItemDiscount(TypedDict): + class UpcomingParamsScheduleDetailsPhaseAddInvoiceItemDiscount(TypedDict): coupon: NotRequired[str] """ ID of the coupon to create a new discount for. @@ -2871,7 +5073,7 @@ class UpcomingLinesParamsSubscriptionItemDiscount(TypedDict): ID of the promotion code to create a new discount for. """ - class UpcomingLinesParamsSubscriptionItemPriceData(TypedDict): + class UpcomingParamsScheduleDetailsPhaseAddInvoiceItemPriceData(TypedDict): currency: str """ 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). @@ -2880,10 +5082,6 @@ class UpcomingLinesParamsSubscriptionItemPriceData(TypedDict): """ The ID of the product that this price will belong to. """ - recurring: "Invoice.UpcomingLinesParamsSubscriptionItemPriceDataRecurring" - """ - The recurring components of a price such as `interval` and `interval_count`. - """ tax_behavior: NotRequired[ Literal["exclusive", "inclusive", "unspecified"] ] @@ -2899,411 +5097,295 @@ class UpcomingLinesParamsSubscriptionItemPriceData(TypedDict): Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - class UpcomingLinesParamsSubscriptionItemPriceDataRecurring(TypedDict): - interval: Literal["day", "month", "week", "year"] + class UpcomingParamsScheduleDetailsPhaseAutomaticTax(TypedDict): + enabled: bool """ - Specifies billing frequency. Either `day`, `week`, `month` or `year`. + Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription. """ - interval_count: NotRequired[int] + liability: NotRequired[ + "Invoice.UpcomingParamsScheduleDetailsPhaseAutomaticTaxLiability" + ] """ - The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. """ - class UpcomingParams(RequestOptions): - automatic_tax: NotRequired["Invoice.UpcomingParamsAutomaticTax"] - """ - Settings for automatic tax lookup for this invoice preview. - """ - coupon: NotRequired[str] - """ - The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. - """ - currency: NotRequired[str] - """ - The currency to preview this invoice in. Defaults to that of `customer` if not specified. - """ - customer: NotRequired[str] + class UpcomingParamsScheduleDetailsPhaseAutomaticTaxLiability(TypedDict): + account: NotRequired[str] """ - The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + The connected account being referenced when `type` is `account`. """ - customer_details: NotRequired["Invoice.UpcomingParamsCustomerDetails"] + type: Literal["account", "self"] """ - Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + Type of the account referenced in the request. """ - discounts: NotRequired[ - "Literal['']|List[Invoice.UpcomingParamsDiscount]" - ] + + class UpcomingParamsScheduleDetailsPhaseBillingThresholds(TypedDict): + amount_gte: NotRequired[int] """ - The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts. + Monetary threshold that triggers the subscription to advance to a new billing period """ - expand: NotRequired[List[str]] + reset_billing_cycle_anchor: NotRequired[bool] """ - Specifies which fields in the response should be expanded. + Indicates if the `billing_cycle_anchor` should be reset when a threshold is reached. If true, `billing_cycle_anchor` will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged. """ - invoice_items: NotRequired[List["Invoice.UpcomingParamsInvoiceItem"]] + + class UpcomingParamsScheduleDetailsPhaseDiscount(TypedDict): + coupon: NotRequired[str] """ - List of invoice items to add or update in the upcoming invoice preview. + ID of the coupon to create a new discount for. """ - issuer: NotRequired["Invoice.UpcomingParamsIssuer"] + discount: NotRequired[str] """ - The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + ID of an existing discount on the object (or one of its ancestors) to reuse. """ - on_behalf_of: NotRequired["Literal['']|str"] + promotion_code: NotRequired[str] """ - The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. + ID of the promotion code to create a new discount for. """ - schedule: NotRequired[str] + + class UpcomingParamsScheduleDetailsPhaseInvoiceSettings(TypedDict): + account_tax_ids: NotRequired["Literal['']|List[str]"] """ - The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. + 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. """ - subscription: NotRequired[str] + days_until_due: NotRequired[int] """ - The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a `subscription_items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_items` is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions. + Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be `null` for subscription schedules where `billing=charge_automatically`. """ - subscription_billing_cycle_anchor: NotRequired[ - "Literal['now', 'unchanged']|int" + issuer: NotRequired[ + "Invoice.UpcomingParamsScheduleDetailsPhaseInvoiceSettingsIssuer" ] """ - For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. - """ - subscription_cancel_at: NotRequired["Literal['']|int"] - """ - A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. - """ - subscription_cancel_at_period_end: NotRequired[bool] - """ - Boolean indicating whether this subscription should cancel at the end of the current period. + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. """ - subscription_cancel_now: NotRequired[bool] + + class UpcomingParamsScheduleDetailsPhaseInvoiceSettingsIssuer(TypedDict): + account: NotRequired[str] """ - This simulates the subscription being canceled or expired immediately. + The connected account being referenced when `type` is `account`. """ - subscription_default_tax_rates: NotRequired["Literal['']|List[str]"] + type: Literal["account", "self"] """ - If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. + Type of the account referenced in the request. """ - subscription_items: NotRequired[ - List["Invoice.UpcomingParamsSubscriptionItem"] + + class UpcomingParamsScheduleDetailsPhaseItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|Invoice.UpcomingParamsScheduleDetailsPhaseItemBillingThresholds" ] """ - A list of up to 20 subscription items, each with an attached price. + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. """ - subscription_proration_behavior: NotRequired[ - Literal["always_invoice", "create_prorations", "none"] + discounts: NotRequired[ + "Literal['']|List[Invoice.UpcomingParamsScheduleDetailsPhaseItemDiscount]" ] """ - Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. - """ - subscription_proration_date: NotRequired[int] - """ - If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'. + The coupons to redeem into discounts for the subscription item. """ - subscription_resume_at: NotRequired[Literal["now"]] + metadata: NotRequired[Dict[str, str]] """ - For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a configuration item. Metadata on a configuration item will update the underlying subscription item's `metadata` when the phase is entered, adding new keys and replacing existing keys. Individual keys in the subscription item's `metadata` can be unset by posting an empty value to them in the configuration item's `metadata`. To unset all keys in the subscription item's `metadata`, update the subscription item directly or unset every key individually from the configuration item's `metadata`. """ - subscription_start_date: NotRequired[int] + plan: NotRequired[str] """ - Date a subscription is intended to start (can be future or past). + The plan ID to subscribe to. You may specify the same ID in `plan` and `price`. """ - subscription_trial_end: NotRequired["Literal['now']|int"] + price: NotRequired[str] """ - If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required. + The ID of the price object. """ - subscription_trial_from_plan: NotRequired[bool] + price_data: NotRequired[ + "Invoice.UpcomingParamsScheduleDetailsPhaseItemPriceData" + ] """ - Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `subscription_trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more. + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ - - class UpcomingParamsAutomaticTax(TypedDict): - enabled: bool + quantity: NotRequired[int] """ - Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. + Quantity for the given price. Can be set only if the price's `usage_type` is `licensed` and not `metered`. """ - liability: NotRequired["Invoice.UpcomingParamsAutomaticTaxLiability"] + tax_rates: NotRequired["Literal['']|List[str]"] """ - The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. """ - class UpcomingParamsAutomaticTaxLiability(TypedDict): - account: NotRequired[str] - """ - The connected account being referenced when `type` is `account`. - """ - type: Literal["account", "self"] + class UpcomingParamsScheduleDetailsPhaseItemBillingThresholds(TypedDict): + usage_gte: int """ - Type of the account referenced in the request. + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) """ - class UpcomingParamsCustomerDetails(TypedDict): - address: NotRequired[ - "Literal['']|Invoice.UpcomingParamsCustomerDetailsAddress" - ] - """ - The customer's address. - """ - shipping: NotRequired[ - "Literal['']|Invoice.UpcomingParamsCustomerDetailsShipping" - ] - """ - The customer's shipping information. Appears on invoices emailed to this customer. - """ - tax: NotRequired["Invoice.UpcomingParamsCustomerDetailsTax"] + class UpcomingParamsScheduleDetailsPhaseItemDiscount(TypedDict): + coupon: NotRequired[str] """ - Tax details about the customer. + ID of the coupon to create a new discount for. """ - tax_exempt: NotRequired[ - "Literal['']|Literal['exempt', 'none', 'reverse']" - ] + discount: NotRequired[str] """ - The customer's tax exemption. One of `none`, `exempt`, or `reverse`. + ID of an existing discount on the object (or one of its ancestors) to reuse. """ - tax_ids: NotRequired[ - List["Invoice.UpcomingParamsCustomerDetailsTaxId"] - ] + promotion_code: NotRequired[str] """ - The customer's tax IDs. + ID of the promotion code to create a new discount for. """ - class UpcomingParamsCustomerDetailsAddress(TypedDict): - city: NotRequired[str] - """ - City, district, suburb, town, or village. - """ - country: NotRequired[str] + class UpcomingParamsScheduleDetailsPhaseItemPriceData(TypedDict): + currency: str """ - Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + 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). """ - line1: NotRequired[str] + product: str """ - Address line 1 (e.g., street, PO Box, or company name). + The ID of the product that this price will belong to. """ - line2: NotRequired[str] + recurring: "Invoice.UpcomingParamsScheduleDetailsPhaseItemPriceDataRecurring" """ - Address line 2 (e.g., apartment, suite, unit, or building). + The recurring components of a price such as `interval` and `interval_count`. """ - postal_code: NotRequired[str] + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] """ - ZIP or postal code. + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. """ - state: NotRequired[str] + unit_amount: NotRequired[int] """ - State, county, province, or region. + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. """ - - class UpcomingParamsCustomerDetailsShipping(TypedDict): - address: "Invoice.UpcomingParamsCustomerDetailsShippingAddress" + unit_amount_decimal: NotRequired[str] """ - Customer shipping address. + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - name: str + + class UpcomingParamsScheduleDetailsPhaseItemPriceDataRecurring(TypedDict): + interval: Literal["day", "month", "week", "year"] """ - Customer name. + Specifies billing frequency. Either `day`, `week`, `month` or `year`. """ - phone: NotRequired[str] + interval_count: NotRequired[int] """ - Customer phone (including extension). + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ - class UpcomingParamsCustomerDetailsShippingAddress(TypedDict): - city: NotRequired[str] + class UpcomingParamsScheduleDetailsPhaseTransferData(TypedDict): + amount_percent: NotRequired[float] """ - City, district, suburb, town, or village. + 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. """ - country: NotRequired[str] + destination: str """ - Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + ID of an existing, connected Stripe account. """ - line1: NotRequired[str] + + class UpcomingParamsSubscriptionDetails(TypedDict): + billing_cycle_anchor: NotRequired["Literal['now', 'unchanged']|int"] """ - Address line 1 (e.g., street, PO Box, or company name). + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. """ - line2: NotRequired[str] + cancel_at: NotRequired["Literal['']|int"] """ - Address line 2 (e.g., apartment, suite, unit, or building). + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. """ - postal_code: NotRequired[str] + cancel_at_period_end: NotRequired[bool] """ - ZIP or postal code. + Boolean indicating whether this subscription should cancel at the end of the current period. """ - state: NotRequired[str] + cancel_now: NotRequired[bool] """ - State, county, province, or region. + This simulates the subscription being canceled or expired immediately. """ - - class UpcomingParamsCustomerDetailsTax(TypedDict): - ip_address: NotRequired["Literal['']|str"] + default_tax_rates: NotRequired["Literal['']|List[str]"] """ - A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes. + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. """ - - class UpcomingParamsCustomerDetailsTaxId(TypedDict): - type: Literal[ - "ad_nrt", - "ae_trn", - "ar_cuit", - "au_abn", - "au_arn", - "bg_uic", - "bh_vat", - "bo_tin", - "br_cnpj", - "br_cpf", - "ca_bn", - "ca_gst_hst", - "ca_pst_bc", - "ca_pst_mb", - "ca_pst_sk", - "ca_qst", - "ch_vat", - "cl_tin", - "cn_tin", - "co_nit", - "cr_tin", - "do_rcn", - "ec_ruc", - "eg_tin", - "es_cif", - "eu_oss_vat", - "eu_vat", - "gb_vat", - "ge_vat", - "hk_br", - "hu_tin", - "id_npwp", - "il_vat", - "in_gst", - "is_vat", - "jp_cn", - "jp_rn", - "jp_trn", - "ke_pin", - "kr_brn", - "kz_bin", - "li_uid", - "mx_rfc", - "my_frp", - "my_itn", - "my_sst", - "ng_tin", - "no_vat", - "no_voec", - "nz_gst", - "om_vat", - "pe_ruc", - "ph_tin", - "ro_tin", - "rs_pib", - "ru_inn", - "ru_kpp", - "sa_vat", - "sg_gst", - "sg_uen", - "si_tin", - "sv_nit", - "th_vat", - "tr_tin", - "tw_vat", - "ua_vat", - "us_ein", - "uy_ruc", - "ve_rif", - "vn_tin", - "za_vat", + items: NotRequired[ + List["Invoice.UpcomingParamsSubscriptionDetailsItem"] ] """ - Type of the tax ID, one of `ad_nrt`, `ae_trn`, `ar_cuit`, `au_abn`, `au_arn`, `bg_uic`, `bh_vat`, `bo_tin`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_vat`, `cl_tin`, `cn_tin`, `co_nit`, `cr_tin`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `eu_oss_vat`, `eu_vat`, `gb_vat`, `ge_vat`, `hk_br`, `hu_tin`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kr_brn`, `kz_bin`, `li_uid`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sv_nit`, `th_vat`, `tr_tin`, `tw_vat`, `ua_vat`, `us_ein`, `uy_ruc`, `ve_rif`, `vn_tin`, or `za_vat` + A list of up to 20 subscription items, each with an attached price. """ - value: str + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] """ - Value of the tax ID. + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. """ - - class UpcomingParamsDiscount(TypedDict): - coupon: NotRequired[str] + proration_date: NotRequired[int] """ - ID of the coupon to create a new discount for. + If previewing an update to a subscription, and doing proration, `subscription_details.proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_details.items`, or `subscription_details.trial_end` are required. Also, `subscription_details.proration_behavior` cannot be set to 'none'. """ - discount: NotRequired[str] + resume_at: NotRequired[Literal["now"]] """ - ID of an existing discount on the object (or one of its ancestors) to reuse. + For paused subscriptions, setting `subscription_details.resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. """ - promotion_code: NotRequired[str] + start_date: NotRequired[int] """ - ID of the promotion code to create a new discount for. + Date a subscription is intended to start (can be future or past). """ - - class UpcomingParamsInvoiceItem(TypedDict): - amount: NotRequired[int] + trial_end: NotRequired["Literal['now']|int"] """ - The integer amount in cents (or local equivalent) of previewed invoice item. + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_details.items` or `subscription` is required. """ - currency: NotRequired[str] + + class UpcomingParamsSubscriptionDetailsItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|Invoice.UpcomingParamsSubscriptionDetailsItemBillingThresholds" + ] """ - 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). Only applicable to new invoice items. + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. """ - description: NotRequired[str] + clear_usage: NotRequired[bool] """ - An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + Delete all usage for a given subscription item. Allowed only when `deleted` is set to `true` and the current plan's `usage_type` is `metered`. """ - discountable: NotRequired[bool] + deleted: NotRequired[bool] """ - Explicitly controls whether discounts apply to this invoice item. Defaults to true, except for negative invoice items. + A flag that, if set to `true`, will delete the specified item. """ discounts: NotRequired[ - "Literal['']|List[Invoice.UpcomingParamsInvoiceItemDiscount]" + "Literal['']|List[Invoice.UpcomingParamsSubscriptionDetailsItemDiscount]" ] """ - The coupons to redeem into discounts for the invoice item in the preview. + The coupons to redeem into discounts for the subscription item. """ - invoiceitem: NotRequired[str] + id: NotRequired[str] """ - The ID of the invoice item to update in preview. If not specified, a new invoice item will be added to the preview of the upcoming invoice. + Subscription item to update. """ metadata: NotRequired["Literal['']|Dict[str, str]"] """ 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. """ - period: NotRequired["Invoice.UpcomingParamsInvoiceItemPeriod"] + plan: NotRequired[str] """ - The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + Plan ID for this item, as a string. """ price: NotRequired[str] """ - The ID of the price object. + The ID of the price object. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided. """ - price_data: NotRequired["Invoice.UpcomingParamsInvoiceItemPriceData"] + price_data: NotRequired[ + "Invoice.UpcomingParamsSubscriptionDetailsItemPriceData" + ] """ Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ quantity: NotRequired[int] """ - Non-negative integer. The quantity of units for the invoice item. - """ - tax_behavior: NotRequired[ - Literal["exclusive", "inclusive", "unspecified"] - ] - """ - Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. - """ - tax_code: NotRequired["Literal['']|str"] - """ - A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + Quantity for this item. """ tax_rates: NotRequired["Literal['']|List[str]"] """ - The tax rates that apply to the item. When set, any `default_tax_rates` do not apply to this item. - """ - unit_amount: NotRequired[int] - """ - The integer unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer's account, pass a negative unit_amount. + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. """ - unit_amount_decimal: NotRequired[str] + + class UpcomingParamsSubscriptionDetailsItemBillingThresholds(TypedDict): + usage_gte: int """ - Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) """ - class UpcomingParamsInvoiceItemDiscount(TypedDict): + class UpcomingParamsSubscriptionDetailsItemDiscount(TypedDict): coupon: NotRequired[str] """ ID of the coupon to create a new discount for. @@ -3317,17 +5399,7 @@ class UpcomingParamsInvoiceItemDiscount(TypedDict): ID of the promotion code to create a new discount for. """ - class UpcomingParamsInvoiceItemPeriod(TypedDict): - end: int - """ - The end of the period, which must be greater than or equal to the start. This value is inclusive. - """ - start: int - """ - The start of the period. This value is inclusive. - """ - - class UpcomingParamsInvoiceItemPriceData(TypedDict): + class UpcomingParamsSubscriptionDetailsItemPriceData(TypedDict): currency: str """ 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). @@ -3336,6 +5408,10 @@ class UpcomingParamsInvoiceItemPriceData(TypedDict): """ The ID of the product that this price will belong to. """ + recurring: "Invoice.UpcomingParamsSubscriptionDetailsItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ tax_behavior: NotRequired[ Literal["exclusive", "inclusive", "unspecified"] ] @@ -3351,14 +5427,14 @@ class UpcomingParamsInvoiceItemPriceData(TypedDict): Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - class UpcomingParamsIssuer(TypedDict): - account: NotRequired[str] + class UpcomingParamsSubscriptionDetailsItemPriceDataRecurring(TypedDict): + interval: Literal["day", "month", "week", "year"] """ - The connected account being referenced when `type` is `account`. + Specifies billing frequency. Either `day`, `week`, `month` or `year`. """ - type: Literal["account", "self"] + interval_count: NotRequired[int] """ - Type of the account referenced in the request. + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ class UpcomingParamsSubscriptionItem(TypedDict): @@ -3849,6 +5925,46 @@ async def create_async( ), ) + @classmethod + def create_preview( + cls, **params: Unpack["Invoice.CreatePreviewParams"] + ) -> "Invoice": + """ + At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice. + + Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer's discount. + + You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_details.proration_date value passed in the request. + """ + return cast( + "Invoice", + cls._static_request( + "post", + "/v1/invoices/create_preview", + params=params, + ), + ) + + @classmethod + async def create_preview_async( + cls, **params: Unpack["Invoice.CreatePreviewParams"] + ) -> "Invoice": + """ + At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice. + + Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer's discount. + + You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_details.proration_date value passed in the request. + """ + return cast( + "Invoice", + await cls._static_request_async( + "post", + "/v1/invoices/create_preview", + params=params, + ), + ) + @classmethod def _cls_delete( cls, sid: str, **params: Unpack["Invoice.DeleteParams"] diff --git a/stripe/_invoice_service.py b/stripe/_invoice_service.py index d21530752..4f076c612 100644 --- a/stripe/_invoice_service.py +++ b/stripe/_invoice_service.py @@ -627,289 +627,1875 @@ class CreateParamsTransferData(TypedDict): ID of an existing, connected Stripe account. """ - class DeleteParams(TypedDict): - pass - - class FinalizeInvoiceParams(TypedDict): - auto_advance: NotRequired[bool] + class CreatePreviewParams(TypedDict): + automatic_tax: NotRequired[ + "InvoiceService.CreatePreviewParamsAutomaticTax" + ] """ - Controls whether Stripe performs [automatic collection](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action. + Settings for automatic tax lookup for this invoice preview. + """ + coupon: NotRequired[str] + """ + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + """ + currency: NotRequired[str] + """ + The currency to preview this invoice in. Defaults to that of `customer` if not specified. + """ + customer: NotRequired[str] + """ + The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + """ + customer_details: NotRequired[ + "InvoiceService.CreatePreviewParamsCustomerDetails" + ] + """ + Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.CreatePreviewParamsDiscount]" + ] + """ + The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts. """ expand: NotRequired[List[str]] """ Specifies which fields in the response should be expanded. """ + invoice_items: NotRequired[ + List["InvoiceService.CreatePreviewParamsInvoiceItem"] + ] + """ + List of invoice items to add or update in the upcoming invoice preview. + """ + issuer: NotRequired["InvoiceService.CreatePreviewParamsIssuer"] + """ + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + """ + on_behalf_of: NotRequired["Literal['']|str"] + """ + The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. + """ + schedule: NotRequired[str] + """ + The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. + """ + schedule_details: NotRequired[ + "InvoiceService.CreatePreviewParamsScheduleDetails" + ] + """ + The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields. + """ + subscription: NotRequired[str] + """ + The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a `subscription_items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_items` is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions. + """ + subscription_details: NotRequired[ + "InvoiceService.CreatePreviewParamsSubscriptionDetails" + ] + """ + The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields. + """ - class ListParams(TypedDict): - collection_method: NotRequired[ - Literal["charge_automatically", "send_invoice"] + class CreatePreviewParamsAutomaticTax(TypedDict): + enabled: bool + """ + Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. + """ + liability: NotRequired[ + "InvoiceService.CreatePreviewParamsAutomaticTaxLiability" ] """ - The collection method of the invoice to retrieve. Either `charge_automatically` or `send_invoice`. + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. """ - created: NotRequired["InvoiceService.ListParamsCreated|int"] + + class CreatePreviewParamsAutomaticTaxLiability(TypedDict): + account: NotRequired[str] """ - Only return invoices that were created during the given date interval. + The connected account being referenced when `type` is `account`. """ - customer: NotRequired[str] + type: Literal["account", "self"] """ - Only return invoices for the customer specified by this customer ID. + Type of the account referenced in the request. """ - due_date: NotRequired["InvoiceService.ListParamsDueDate|int"] - ending_before: NotRequired[str] + + class CreatePreviewParamsCustomerDetails(TypedDict): + address: NotRequired[ + "Literal['']|InvoiceService.CreatePreviewParamsCustomerDetailsAddress" + ] """ - A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. + The customer's address. """ - expand: NotRequired[List[str]] + shipping: NotRequired[ + "Literal['']|InvoiceService.CreatePreviewParamsCustomerDetailsShipping" + ] """ - Specifies which fields in the response should be expanded. + The customer's shipping information. Appears on invoices emailed to this customer. """ - limit: NotRequired[int] + tax: NotRequired[ + "InvoiceService.CreatePreviewParamsCustomerDetailsTax" + ] """ - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + Tax details about the customer. """ - starting_after: NotRequired[str] + tax_exempt: NotRequired[ + "Literal['']|Literal['exempt', 'none', 'reverse']" + ] """ - A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. + The customer's tax exemption. One of `none`, `exempt`, or `reverse`. """ - status: NotRequired[ - Literal["draft", "open", "paid", "uncollectible", "void"] + tax_ids: NotRequired[ + List["InvoiceService.CreatePreviewParamsCustomerDetailsTaxId"] ] """ - The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://stripe.com/docs/billing/invoices/workflow#workflow-overview) + The customer's tax IDs. """ - subscription: NotRequired[str] + + class CreatePreviewParamsCustomerDetailsAddress(TypedDict): + city: NotRequired[str] """ - Only return invoices for the subscription specified by this subscription ID. + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. """ - class ListParamsCreated(TypedDict): - gt: NotRequired[int] + class CreatePreviewParamsCustomerDetailsShipping(TypedDict): + address: "InvoiceService.CreatePreviewParamsCustomerDetailsShippingAddress" """ - Minimum value to filter by (exclusive) + Customer shipping address. """ - gte: NotRequired[int] + name: str """ - Minimum value to filter by (inclusive) + Customer name. """ - lt: NotRequired[int] + phone: NotRequired[str] """ - Maximum value to filter by (exclusive) + Customer phone (including extension). """ - lte: NotRequired[int] + + class CreatePreviewParamsCustomerDetailsShippingAddress(TypedDict): + city: NotRequired[str] """ - Maximum value to filter by (inclusive) + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. """ - class ListParamsDueDate(TypedDict): - gt: NotRequired[int] + class CreatePreviewParamsCustomerDetailsTax(TypedDict): + ip_address: NotRequired["Literal['']|str"] + """ + A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes. + """ + + class CreatePreviewParamsCustomerDetailsTaxId(TypedDict): + type: Literal[ + "ad_nrt", + "ae_trn", + "ar_cuit", + "au_abn", + "au_arn", + "bg_uic", + "bh_vat", + "bo_tin", + "br_cnpj", + "br_cpf", + "ca_bn", + "ca_gst_hst", + "ca_pst_bc", + "ca_pst_mb", + "ca_pst_sk", + "ca_qst", + "ch_vat", + "cl_tin", + "cn_tin", + "co_nit", + "cr_tin", + "do_rcn", + "ec_ruc", + "eg_tin", + "es_cif", + "eu_oss_vat", + "eu_vat", + "gb_vat", + "ge_vat", + "hk_br", + "hu_tin", + "id_npwp", + "il_vat", + "in_gst", + "is_vat", + "jp_cn", + "jp_rn", + "jp_trn", + "ke_pin", + "kr_brn", + "kz_bin", + "li_uid", + "mx_rfc", + "my_frp", + "my_itn", + "my_sst", + "ng_tin", + "no_vat", + "no_voec", + "nz_gst", + "om_vat", + "pe_ruc", + "ph_tin", + "ro_tin", + "rs_pib", + "ru_inn", + "ru_kpp", + "sa_vat", + "sg_gst", + "sg_uen", + "si_tin", + "sv_nit", + "th_vat", + "tr_tin", + "tw_vat", + "ua_vat", + "us_ein", + "uy_ruc", + "ve_rif", + "vn_tin", + "za_vat", + ] + """ + Type of the tax ID, one of `ad_nrt`, `ae_trn`, `ar_cuit`, `au_abn`, `au_arn`, `bg_uic`, `bh_vat`, `bo_tin`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_vat`, `cl_tin`, `cn_tin`, `co_nit`, `cr_tin`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `eu_oss_vat`, `eu_vat`, `gb_vat`, `ge_vat`, `hk_br`, `hu_tin`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kr_brn`, `kz_bin`, `li_uid`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sv_nit`, `th_vat`, `tr_tin`, `tw_vat`, `ua_vat`, `us_ein`, `uy_ruc`, `ve_rif`, `vn_tin`, or `za_vat` + """ + value: str + """ + Value of the tax ID. + """ + + class CreatePreviewParamsDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsInvoiceItem(TypedDict): + amount: NotRequired[int] + """ + The integer amount in cents (or local equivalent) of previewed invoice item. + """ + currency: NotRequired[str] + """ + 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). Only applicable to new invoice items. + """ + description: NotRequired[str] + """ + An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + """ + discountable: NotRequired[bool] + """ + Explicitly controls whether discounts apply to this invoice item. Defaults to true, except for negative invoice items. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.CreatePreviewParamsInvoiceItemDiscount]" + ] + """ + The coupons to redeem into discounts for the invoice item in the preview. + """ + invoiceitem: NotRequired[str] + """ + The ID of the invoice item to update in preview. If not specified, a new invoice item will be added to the preview of the upcoming invoice. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + period: NotRequired[ + "InvoiceService.CreatePreviewParamsInvoiceItemPeriod" + ] + """ + The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "InvoiceService.CreatePreviewParamsInvoiceItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Non-negative integer. The quantity of units for the invoice item. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + tax_code: NotRequired["Literal['']|str"] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates that apply to the item. When set, any `default_tax_rates` do not apply to this item. + """ + unit_amount: NotRequired[int] + """ + The integer unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer's account, pass a negative unit_amount. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsInvoiceItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsInvoiceItemPeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class CreatePreviewParamsInvoiceItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsIssuer(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class CreatePreviewParamsScheduleDetails(TypedDict): + end_behavior: NotRequired[Literal["cancel", "release"]] + """ + Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running. `cancel` will end the subscription schedule and cancel the underlying subscription. + """ + phases: NotRequired[ + List["InvoiceService.CreatePreviewParamsScheduleDetailsPhase"] + ] + """ + List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the `end_date` of one phase will always equal the `start_date` of the next phase. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + In cases where the `schedule_details` params update the currently active phase, specifies if and how to prorate at the time of the request. + """ + + class CreatePreviewParamsScheduleDetailsPhase(TypedDict): + add_invoice_items: NotRequired[ + List[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItem" + ] + ] + """ + A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. You may pass up to 20 items. + """ + application_fee_percent: NotRequired[float] + """ + 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 application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions). + """ + automatic_tax: NotRequired[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseAutomaticTax" + ] + """ + Automatic tax settings for this phase. + """ + billing_cycle_anchor: NotRequired[Literal["automatic", "phase_start"]] + """ + Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle). + """ + billing_thresholds: NotRequired[ + "Literal['']|InvoiceService.CreatePreviewParamsScheduleDetailsPhaseBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds. + """ + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] + """ + Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically` on creation. + """ + coupon: NotRequired[str] + """ + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + """ + currency: NotRequired[str] + """ + 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). + """ + default_payment_method: NotRequired[str] + """ + ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer's invoice settings. + """ + default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will set the Subscription's [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates), which means they will be the Invoice's [`default_tax_rates`](https://stripe.com/docs/api/invoices/create#create_invoice-default_tax_rates) for any Invoices issued by the Subscription during this Phase. + """ + description: NotRequired["Literal['']|str"] + """ + Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.CreatePreviewParamsScheduleDetailsPhaseDiscount]" + ] + """ + The coupons to redeem into discounts for the schedule phase. If not specified, inherits the discount from the subscription's customer. Pass an empty string to avoid inheriting any discounts. + """ + end_date: NotRequired["int|Literal['now']"] + """ + The date at which this phase of the subscription schedule ends. If set, `iterations` must not be set. + """ + invoice_settings: NotRequired[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseInvoiceSettings" + ] + """ + All invoices will be billed using the specified settings. + """ + items: List[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseItem" + ] + """ + List of configuration items, each with an attached price, to apply during this phase of the subscription schedule. + """ + iterations: NotRequired[int] + """ + Integer representing the multiplier applied to the price interval. For example, `iterations=2` applied to a price with `interval=month` and `interval_count=3` results in a phase of duration `2 * 3 months = 6 months`. If set, `end_date` must not be set. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a phase. Metadata on a schedule's phase will update the underlying subscription's `metadata` when the phase is entered, adding new keys and replacing existing keys in the subscription's `metadata`. Individual keys in the subscription's `metadata` can be unset by posting an empty value to them in the phase's `metadata`. To unset all keys in the subscription's `metadata`, update the subscription directly or unset every key individually from the phase's `metadata`. + """ + on_behalf_of: NotRequired[str] + """ + The account on behalf of which to charge, for each of the associated subscription's invoices. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + Whether the subscription schedule will create [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when transitioning to this phase. The default value is `create_prorations`. This setting controls prorations when a phase is started asynchronously and it is persisted as a field on the phase. It's different from the request-level [proration_behavior](https://stripe.com/docs/api/subscription_schedules/update#update_subscription_schedule-proration_behavior) parameter which controls what happens if the update request affects the billing configuration of the current phase. + """ + start_date: NotRequired["int|Literal['now']"] + """ + The date at which this phase of the subscription schedule starts or `now`. Must be set on the first phase. + """ + transfer_data: NotRequired[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseTransferData" + ] + """ + The data with which to automatically create a Transfer for each of the associated subscription's invoices. + """ + trial: NotRequired[bool] + """ + If set to true the entire phase is counted as a trial and the customer will not be charged for any fees. + """ + trial_end: NotRequired["int|Literal['now']"] + """ + Sets the phase to trialing from the start date to this date. Must be before the phase end date, can not be combined with `trial` + """ + + class CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItem(TypedDict): + discounts: NotRequired[ + List[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItemDiscount" + ] + ] + """ + The coupons to redeem into discounts for the item. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for this item. Defaults to 1. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates which apply to the item. When set, the `default_tax_rates` do not apply to this item. + """ + + class CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItemDiscount( + TypedDict, + ): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsScheduleDetailsPhaseAddInvoiceItemPriceData( + TypedDict, + ): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsScheduleDetailsPhaseAutomaticTax(TypedDict): + enabled: bool + """ + Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription. + """ + liability: NotRequired[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseAutomaticTaxLiability" + ] + """ + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. + """ + + class CreatePreviewParamsScheduleDetailsPhaseAutomaticTaxLiability( + TypedDict, + ): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class CreatePreviewParamsScheduleDetailsPhaseBillingThresholds(TypedDict): + amount_gte: NotRequired[int] + """ + Monetary threshold that triggers the subscription to advance to a new billing period + """ + reset_billing_cycle_anchor: NotRequired[bool] + """ + Indicates if the `billing_cycle_anchor` should be reset when a threshold is reached. If true, `billing_cycle_anchor` will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged. + """ + + class CreatePreviewParamsScheduleDetailsPhaseDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsScheduleDetailsPhaseInvoiceSettings(TypedDict): + account_tax_ids: NotRequired["Literal['']|List[str]"] + """ + 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. + """ + days_until_due: NotRequired[int] + """ + Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be `null` for subscription schedules where `billing=charge_automatically`. + """ + issuer: NotRequired[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseInvoiceSettingsIssuer" + ] + """ + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + """ + + class CreatePreviewParamsScheduleDetailsPhaseInvoiceSettingsIssuer( + TypedDict, + ): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class CreatePreviewParamsScheduleDetailsPhaseItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|InvoiceService.CreatePreviewParamsScheduleDetailsPhaseItemBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.CreatePreviewParamsScheduleDetailsPhaseItemDiscount]" + ] + """ + The coupons to redeem into discounts for the subscription item. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a configuration item. Metadata on a configuration item will update the underlying subscription item's `metadata` when the phase is entered, adding new keys and replacing existing keys. Individual keys in the subscription item's `metadata` can be unset by posting an empty value to them in the configuration item's `metadata`. To unset all keys in the subscription item's `metadata`, update the subscription item directly or unset every key individually from the configuration item's `metadata`. + """ + plan: NotRequired[str] + """ + The plan ID to subscribe to. You may specify the same ID in `plan` and `price`. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for the given price. Can be set only if the price's `usage_type` is `licensed` and not `metered`. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. + """ + + class CreatePreviewParamsScheduleDetailsPhaseItemBillingThresholds( + TypedDict, + ): + usage_gte: int + """ + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) + """ + + class CreatePreviewParamsScheduleDetailsPhaseItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsScheduleDetailsPhaseItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + recurring: "InvoiceService.CreatePreviewParamsScheduleDetailsPhaseItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsScheduleDetailsPhaseItemPriceDataRecurring( + TypedDict, + ): + interval: Literal["day", "month", "week", "year"] + """ + Specifies billing frequency. Either `day`, `week`, `month` or `year`. + """ + interval_count: NotRequired[int] + """ + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). + """ + + class CreatePreviewParamsScheduleDetailsPhaseTransferData(TypedDict): + amount_percent: NotRequired[float] + """ + 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. + """ + destination: str + """ + ID of an existing, connected Stripe account. + """ + + class CreatePreviewParamsSubscriptionDetails(TypedDict): + billing_cycle_anchor: NotRequired["Literal['now', 'unchanged']|int"] + """ + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. + """ + cancel_at: NotRequired["Literal['']|int"] + """ + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. + """ + cancel_at_period_end: NotRequired[bool] + """ + Boolean indicating whether this subscription should cancel at the end of the current period. + """ + cancel_now: NotRequired[bool] + """ + This simulates the subscription being canceled or expired immediately. + """ + default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. + """ + items: NotRequired[ + List["InvoiceService.CreatePreviewParamsSubscriptionDetailsItem"] + ] + """ + A list of up to 20 subscription items, each with an attached price. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. + """ + proration_date: NotRequired[int] + """ + If previewing an update to a subscription, and doing proration, `subscription_details.proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_details.items`, or `subscription_details.trial_end` are required. Also, `subscription_details.proration_behavior` cannot be set to 'none'. + """ + resume_at: NotRequired[Literal["now"]] + """ + For paused subscriptions, setting `subscription_details.resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. + """ + start_date: NotRequired[int] + """ + Date a subscription is intended to start (can be future or past). + """ + trial_end: NotRequired["Literal['now']|int"] + """ + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_details.items` or `subscription` is required. + """ + + class CreatePreviewParamsSubscriptionDetailsItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|InvoiceService.CreatePreviewParamsSubscriptionDetailsItemBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. + """ + clear_usage: NotRequired[bool] + """ + Delete all usage for a given subscription item. Allowed only when `deleted` is set to `true` and the current plan's `usage_type` is `metered`. + """ + deleted: NotRequired[bool] + """ + A flag that, if set to `true`, will delete the specified item. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.CreatePreviewParamsSubscriptionDetailsItemDiscount]" + ] + """ + The coupons to redeem into discounts for the subscription item. + """ + id: NotRequired[str] + """ + Subscription item to update. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + plan: NotRequired[str] + """ + Plan ID for this item, as a string. + """ + price: NotRequired[str] + """ + The ID of the price object. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided. + """ + price_data: NotRequired[ + "InvoiceService.CreatePreviewParamsSubscriptionDetailsItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for this item. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. + """ + + class CreatePreviewParamsSubscriptionDetailsItemBillingThresholds( + TypedDict, + ): + usage_gte: int + """ + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) + """ + + class CreatePreviewParamsSubscriptionDetailsItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class CreatePreviewParamsSubscriptionDetailsItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + recurring: "InvoiceService.CreatePreviewParamsSubscriptionDetailsItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class CreatePreviewParamsSubscriptionDetailsItemPriceDataRecurring( + TypedDict, + ): + interval: Literal["day", "month", "week", "year"] + """ + Specifies billing frequency. Either `day`, `week`, `month` or `year`. + """ + interval_count: NotRequired[int] + """ + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). + """ + + class DeleteParams(TypedDict): + pass + + class FinalizeInvoiceParams(TypedDict): + auto_advance: NotRequired[bool] + """ + Controls whether Stripe performs [automatic collection](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action. + """ + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + class ListParams(TypedDict): + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] + """ + The collection method of the invoice to retrieve. Either `charge_automatically` or `send_invoice`. + """ + created: NotRequired["InvoiceService.ListParamsCreated|int"] + """ + Only return invoices that were created during the given date interval. + """ + customer: NotRequired[str] + """ + Only return invoices for the customer specified by this customer ID. + """ + due_date: NotRequired["InvoiceService.ListParamsDueDate|int"] + ending_before: NotRequired[str] + """ + A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. + """ + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + limit: NotRequired[int] + """ + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + """ + starting_after: NotRequired[str] + """ + A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. + """ + status: NotRequired[ + Literal["draft", "open", "paid", "uncollectible", "void"] + ] + """ + The status of the invoice, one of `draft`, `open`, `paid`, `uncollectible`, or `void`. [Learn more](https://stripe.com/docs/billing/invoices/workflow#workflow-overview) + """ + subscription: NotRequired[str] + """ + Only return invoices for the subscription specified by this subscription ID. + """ + + class ListParamsCreated(TypedDict): + gt: NotRequired[int] + """ + Minimum value to filter by (exclusive) + """ + gte: NotRequired[int] + """ + Minimum value to filter by (inclusive) + """ + lt: NotRequired[int] + """ + Maximum value to filter by (exclusive) + """ + lte: NotRequired[int] + """ + Maximum value to filter by (inclusive) + """ + + class ListParamsDueDate(TypedDict): + gt: NotRequired[int] + """ + Minimum value to filter by (exclusive) + """ + gte: NotRequired[int] + """ + Minimum value to filter by (inclusive) + """ + lt: NotRequired[int] + """ + Maximum value to filter by (exclusive) + """ + lte: NotRequired[int] + """ + Maximum value to filter by (inclusive) + """ + + class MarkUncollectibleParams(TypedDict): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + class PayParams(TypedDict): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + forgive: NotRequired[bool] + """ + In cases where the source used to pay the invoice has insufficient funds, passing `forgive=true` controls whether a charge should be attempted for the full amount available on the source, up to the amount to fully pay the invoice. This effectively forgives the difference between the amount available on the source and the amount due. + + Passing `forgive=false` will fail the charge if the source hasn't been pre-funded with the right amount. An example for this case is with ACH Credit Transfers and wires: if the amount wired is less than the amount due by a small amount, you might want to forgive the difference. Defaults to `false`. + """ + mandate: NotRequired["Literal['']|str"] + """ + ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the payment_method param or the invoice's default_payment_method or default_source, if set. + """ + off_session: NotRequired[bool] + """ + Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `true` (off-session). + """ + paid_out_of_band: NotRequired[bool] + """ + Boolean representing whether an invoice is paid outside of Stripe. This will result in no charge being made. Defaults to `false`. + """ + payment_method: NotRequired[str] + """ + A PaymentMethod to be charged. The PaymentMethod must be the ID of a PaymentMethod belonging to the customer associated with the invoice being paid. + """ + source: NotRequired[str] + """ + A payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid. + """ + + class RetrieveParams(TypedDict): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + class SearchParams(TypedDict): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + limit: NotRequired[int] + """ + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + """ + page: NotRequired[str] + """ + A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results. + """ + query: str + """ + The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for invoices](https://stripe.com/docs/search#query-fields-for-invoices). + """ + + class SendInvoiceParams(TypedDict): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + class UpcomingParams(TypedDict): + automatic_tax: NotRequired["InvoiceService.UpcomingParamsAutomaticTax"] + """ + Settings for automatic tax lookup for this invoice preview. + """ + coupon: NotRequired[str] + """ + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + """ + currency: NotRequired[str] + """ + The currency to preview this invoice in. Defaults to that of `customer` if not specified. + """ + customer: NotRequired[str] + """ + The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + """ + customer_details: NotRequired[ + "InvoiceService.UpcomingParamsCustomerDetails" + ] + """ + Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.UpcomingParamsDiscount]" + ] + """ + The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts. + """ + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + invoice_items: NotRequired[ + List["InvoiceService.UpcomingParamsInvoiceItem"] + ] + """ + List of invoice items to add or update in the upcoming invoice preview. + """ + issuer: NotRequired["InvoiceService.UpcomingParamsIssuer"] + """ + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + """ + on_behalf_of: NotRequired["Literal['']|str"] + """ + The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. + """ + schedule: NotRequired[str] + """ + The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. + """ + schedule_details: NotRequired[ + "InvoiceService.UpcomingParamsScheduleDetails" + ] + """ + The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields. + """ + subscription: NotRequired[str] + """ + The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a `subscription_items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_items` is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions. + """ + subscription_billing_cycle_anchor: NotRequired[ + "Literal['now', 'unchanged']|int" + ] + """ + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. This field has been deprecated and will be removed in a future API version. Use `subscription_details.billing_cycle_anchor` instead. + """ + subscription_cancel_at: NotRequired["Literal['']|int"] + """ + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_at` instead. + """ + subscription_cancel_at_period_end: NotRequired[bool] + """ + Boolean indicating whether this subscription should cancel at the end of the current period. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_at_period_end` instead. + """ + subscription_cancel_now: NotRequired[bool] + """ + This simulates the subscription being canceled or expired immediately. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_now` instead. + """ + subscription_default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. This field has been deprecated and will be removed in a future API version. Use `subscription_details.default_tax_rates` instead. + """ + subscription_details: NotRequired[ + "InvoiceService.UpcomingParamsSubscriptionDetails" + ] + """ + The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields. + """ + subscription_items: NotRequired[ + List["InvoiceService.UpcomingParamsSubscriptionItem"] + ] + """ + A list of up to 20 subscription items, each with an attached price. This field has been deprecated and will be removed in a future API version. Use `subscription_details.items` instead. + """ + subscription_proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. This field has been deprecated and will be removed in a future API version. Use `subscription_details.proration_behavior` instead. + """ + subscription_proration_date: NotRequired[int] + """ + If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'. This field has been deprecated and will be removed in a future API version. Use `subscription_details.proration_date` instead. + """ + subscription_resume_at: NotRequired[Literal["now"]] + """ + For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. This field has been deprecated and will be removed in a future API version. Use `subscription_details.resume_at` instead. + """ + subscription_start_date: NotRequired[int] + """ + Date a subscription is intended to start (can be future or past). This field has been deprecated and will be removed in a future API version. Use `subscription_details.start_date` instead. + """ + subscription_trial_end: NotRequired["Literal['now']|int"] + """ + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required. This field has been deprecated and will be removed in a future API version. Use `subscription_details.trial_end` instead. + """ + subscription_trial_from_plan: NotRequired[bool] + """ + Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `subscription_trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more. + """ + + class UpcomingParamsAutomaticTax(TypedDict): + enabled: bool + """ + Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. + """ + liability: NotRequired[ + "InvoiceService.UpcomingParamsAutomaticTaxLiability" + ] + """ + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. + """ + + class UpcomingParamsAutomaticTaxLiability(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class UpcomingParamsCustomerDetails(TypedDict): + address: NotRequired[ + "Literal['']|InvoiceService.UpcomingParamsCustomerDetailsAddress" + ] + """ + The customer's address. + """ + shipping: NotRequired[ + "Literal['']|InvoiceService.UpcomingParamsCustomerDetailsShipping" + ] + """ + The customer's shipping information. Appears on invoices emailed to this customer. + """ + tax: NotRequired["InvoiceService.UpcomingParamsCustomerDetailsTax"] + """ + Tax details about the customer. + """ + tax_exempt: NotRequired[ + "Literal['']|Literal['exempt', 'none', 'reverse']" + ] + """ + The customer's tax exemption. One of `none`, `exempt`, or `reverse`. + """ + tax_ids: NotRequired[ + List["InvoiceService.UpcomingParamsCustomerDetailsTaxId"] + ] + """ + The customer's tax IDs. + """ + + class UpcomingParamsCustomerDetailsAddress(TypedDict): + city: NotRequired[str] + """ + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. + """ + + class UpcomingParamsCustomerDetailsShipping(TypedDict): + address: "InvoiceService.UpcomingParamsCustomerDetailsShippingAddress" + """ + Customer shipping address. + """ + name: str + """ + Customer name. + """ + phone: NotRequired[str] + """ + Customer phone (including extension). + """ + + class UpcomingParamsCustomerDetailsShippingAddress(TypedDict): + city: NotRequired[str] + """ + City, district, suburb, town, or village. + """ + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + line1: NotRequired[str] + """ + Address line 1 (e.g., street, PO Box, or company name). + """ + line2: NotRequired[str] + """ + Address line 2 (e.g., apartment, suite, unit, or building). + """ + postal_code: NotRequired[str] + """ + ZIP or postal code. + """ + state: NotRequired[str] + """ + State, county, province, or region. + """ + + class UpcomingParamsCustomerDetailsTax(TypedDict): + ip_address: NotRequired["Literal['']|str"] + """ + A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes. + """ + + class UpcomingParamsCustomerDetailsTaxId(TypedDict): + type: Literal[ + "ad_nrt", + "ae_trn", + "ar_cuit", + "au_abn", + "au_arn", + "bg_uic", + "bh_vat", + "bo_tin", + "br_cnpj", + "br_cpf", + "ca_bn", + "ca_gst_hst", + "ca_pst_bc", + "ca_pst_mb", + "ca_pst_sk", + "ca_qst", + "ch_vat", + "cl_tin", + "cn_tin", + "co_nit", + "cr_tin", + "do_rcn", + "ec_ruc", + "eg_tin", + "es_cif", + "eu_oss_vat", + "eu_vat", + "gb_vat", + "ge_vat", + "hk_br", + "hu_tin", + "id_npwp", + "il_vat", + "in_gst", + "is_vat", + "jp_cn", + "jp_rn", + "jp_trn", + "ke_pin", + "kr_brn", + "kz_bin", + "li_uid", + "mx_rfc", + "my_frp", + "my_itn", + "my_sst", + "ng_tin", + "no_vat", + "no_voec", + "nz_gst", + "om_vat", + "pe_ruc", + "ph_tin", + "ro_tin", + "rs_pib", + "ru_inn", + "ru_kpp", + "sa_vat", + "sg_gst", + "sg_uen", + "si_tin", + "sv_nit", + "th_vat", + "tr_tin", + "tw_vat", + "ua_vat", + "us_ein", + "uy_ruc", + "ve_rif", + "vn_tin", + "za_vat", + ] + """ + Type of the tax ID, one of `ad_nrt`, `ae_trn`, `ar_cuit`, `au_abn`, `au_arn`, `bg_uic`, `bh_vat`, `bo_tin`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_vat`, `cl_tin`, `cn_tin`, `co_nit`, `cr_tin`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `eu_oss_vat`, `eu_vat`, `gb_vat`, `ge_vat`, `hk_br`, `hu_tin`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kr_brn`, `kz_bin`, `li_uid`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sv_nit`, `th_vat`, `tr_tin`, `tw_vat`, `ua_vat`, `us_ein`, `uy_ruc`, `ve_rif`, `vn_tin`, or `za_vat` + """ + value: str + """ + Value of the tax ID. + """ + + class UpcomingParamsDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class UpcomingParamsInvoiceItem(TypedDict): + amount: NotRequired[int] + """ + The integer amount in cents (or local equivalent) of previewed invoice item. + """ + currency: NotRequired[str] + """ + 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). Only applicable to new invoice items. + """ + description: NotRequired[str] + """ + An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + """ + discountable: NotRequired[bool] + """ + Explicitly controls whether discounts apply to this invoice item. Defaults to true, except for negative invoice items. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.UpcomingParamsInvoiceItemDiscount]" + ] + """ + The coupons to redeem into discounts for the invoice item in the preview. + """ + invoiceitem: NotRequired[str] + """ + The ID of the invoice item to update in preview. If not specified, a new invoice item will be added to the preview of the upcoming invoice. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + period: NotRequired["InvoiceService.UpcomingParamsInvoiceItemPeriod"] + """ + The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "InvoiceService.UpcomingParamsInvoiceItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Non-negative integer. The quantity of units for the invoice item. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + tax_code: NotRequired["Literal['']|str"] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates that apply to the item. When set, any `default_tax_rates` do not apply to this item. + """ + unit_amount: NotRequired[int] + """ + The integer unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer's account, pass a negative unit_amount. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class UpcomingParamsInvoiceItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class UpcomingParamsInvoiceItemPeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class UpcomingParamsInvoiceItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class UpcomingParamsIssuer(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class UpcomingParamsScheduleDetails(TypedDict): + end_behavior: NotRequired[Literal["cancel", "release"]] + """ + Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running. `cancel` will end the subscription schedule and cancel the underlying subscription. + """ + phases: NotRequired[ + List["InvoiceService.UpcomingParamsScheduleDetailsPhase"] + ] + """ + List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the `end_date` of one phase will always equal the `start_date` of the next phase. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + In cases where the `schedule_details` params update the currently active phase, specifies if and how to prorate at the time of the request. + """ + + class UpcomingParamsScheduleDetailsPhase(TypedDict): + add_invoice_items: NotRequired[ + List[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseAddInvoiceItem" + ] + ] """ - Minimum value to filter by (exclusive) + A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. You may pass up to 20 items. """ - gte: NotRequired[int] + application_fee_percent: NotRequired[float] """ - Minimum value to filter by (inclusive) + 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 application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions). """ - lt: NotRequired[int] + automatic_tax: NotRequired[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseAutomaticTax" + ] """ - Maximum value to filter by (exclusive) + Automatic tax settings for this phase. """ - lte: NotRequired[int] + billing_cycle_anchor: NotRequired[Literal["automatic", "phase_start"]] """ - Maximum value to filter by (inclusive) + Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle). """ - - class MarkUncollectibleParams(TypedDict): - expand: NotRequired[List[str]] + billing_thresholds: NotRequired[ + "Literal['']|InvoiceService.UpcomingParamsScheduleDetailsPhaseBillingThresholds" + ] """ - Specifies which fields in the response should be expanded. + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds. """ - - class PayParams(TypedDict): - expand: NotRequired[List[str]] + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] """ - Specifies which fields in the response should be expanded. + Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically` on creation. """ - forgive: NotRequired[bool] + coupon: NotRequired[str] """ - In cases where the source used to pay the invoice has insufficient funds, passing `forgive=true` controls whether a charge should be attempted for the full amount available on the source, up to the amount to fully pay the invoice. This effectively forgives the difference between the amount available on the source and the amount due. - - Passing `forgive=false` will fail the charge if the source hasn't been pre-funded with the right amount. An example for this case is with ACH Credit Transfers and wires: if the amount wired is less than the amount due by a small amount, you might want to forgive the difference. Defaults to `false`. + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. """ - mandate: NotRequired["Literal['']|str"] + currency: NotRequired[str] """ - ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the payment_method param or the invoice's default_payment_method or default_source, if set. + 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). """ - off_session: NotRequired[bool] + default_payment_method: NotRequired[str] """ - Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `true` (off-session). + ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer's invoice settings. """ - paid_out_of_band: NotRequired[bool] + default_tax_rates: NotRequired["Literal['']|List[str]"] """ - Boolean representing whether an invoice is paid outside of Stripe. This will result in no charge being made. Defaults to `false`. + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will set the Subscription's [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates), which means they will be the Invoice's [`default_tax_rates`](https://stripe.com/docs/api/invoices/create#create_invoice-default_tax_rates) for any Invoices issued by the Subscription during this Phase. """ - payment_method: NotRequired[str] + description: NotRequired["Literal['']|str"] """ - A PaymentMethod to be charged. The PaymentMethod must be the ID of a PaymentMethod belonging to the customer associated with the invoice being paid. + Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. """ - source: NotRequired[str] + discounts: NotRequired[ + "Literal['']|List[InvoiceService.UpcomingParamsScheduleDetailsPhaseDiscount]" + ] """ - A payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid. + The coupons to redeem into discounts for the schedule phase. If not specified, inherits the discount from the subscription's customer. Pass an empty string to avoid inheriting any discounts. """ - - class RetrieveParams(TypedDict): - expand: NotRequired[List[str]] + end_date: NotRequired["int|Literal['now']"] """ - Specifies which fields in the response should be expanded. + The date at which this phase of the subscription schedule ends. If set, `iterations` must not be set. """ - - class SearchParams(TypedDict): - expand: NotRequired[List[str]] + invoice_settings: NotRequired[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseInvoiceSettings" + ] """ - Specifies which fields in the response should be expanded. + All invoices will be billed using the specified settings. """ - limit: NotRequired[int] + items: List["InvoiceService.UpcomingParamsScheduleDetailsPhaseItem"] """ - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. + List of configuration items, each with an attached price, to apply during this phase of the subscription schedule. """ - page: NotRequired[str] + iterations: NotRequired[int] """ - A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results. + Integer representing the multiplier applied to the price interval. For example, `iterations=2` applied to a price with `interval=month` and `interval_count=3` results in a phase of duration `2 * 3 months = 6 months`. If set, `end_date` must not be set. """ - query: str + metadata: NotRequired[Dict[str, str]] """ - The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for invoices](https://stripe.com/docs/search#query-fields-for-invoices). + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a phase. Metadata on a schedule's phase will update the underlying subscription's `metadata` when the phase is entered, adding new keys and replacing existing keys in the subscription's `metadata`. Individual keys in the subscription's `metadata` can be unset by posting an empty value to them in the phase's `metadata`. To unset all keys in the subscription's `metadata`, update the subscription directly or unset every key individually from the phase's `metadata`. """ - - class SendInvoiceParams(TypedDict): - expand: NotRequired[List[str]] + on_behalf_of: NotRequired[str] """ - Specifies which fields in the response should be expanded. + The account on behalf of which to charge, for each of the associated subscription's invoices. """ - - class UpcomingParams(TypedDict): - automatic_tax: NotRequired["InvoiceService.UpcomingParamsAutomaticTax"] + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] """ - Settings for automatic tax lookup for this invoice preview. + Whether the subscription schedule will create [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when transitioning to this phase. The default value is `create_prorations`. This setting controls prorations when a phase is started asynchronously and it is persisted as a field on the phase. It's different from the request-level [proration_behavior](https://stripe.com/docs/api/subscription_schedules/update#update_subscription_schedule-proration_behavior) parameter which controls what happens if the update request affects the billing configuration of the current phase. """ - coupon: NotRequired[str] + start_date: NotRequired["int|Literal['now']"] """ - The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + The date at which this phase of the subscription schedule starts or `now`. Must be set on the first phase. """ - currency: NotRequired[str] + transfer_data: NotRequired[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseTransferData" + ] """ - The currency to preview this invoice in. Defaults to that of `customer` if not specified. + The data with which to automatically create a Transfer for each of the associated subscription's invoices. """ - customer: NotRequired[str] + trial: NotRequired[bool] """ - The identifier of the customer whose upcoming invoice you'd like to retrieve. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + If set to true the entire phase is counted as a trial and the customer will not be charged for any fees. """ - customer_details: NotRequired[ - "InvoiceService.UpcomingParamsCustomerDetails" - ] + trial_end: NotRequired["int|Literal['now']"] """ - Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set. + Sets the phase to trialing from the start date to this date. Must be before the phase end date, can not be combined with `trial` """ + + class UpcomingParamsScheduleDetailsPhaseAddInvoiceItem(TypedDict): discounts: NotRequired[ - "Literal['']|List[InvoiceService.UpcomingParamsDiscount]" + List[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseAddInvoiceItemDiscount" + ] ] """ - The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts. + The coupons to redeem into discounts for the item. """ - expand: NotRequired[List[str]] + price: NotRequired[str] """ - Specifies which fields in the response should be expanded. + The ID of the price object. """ - invoice_items: NotRequired[ - List["InvoiceService.UpcomingParamsInvoiceItem"] + price_data: NotRequired[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseAddInvoiceItemPriceData" ] """ - List of invoice items to add or update in the upcoming invoice preview. + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ - issuer: NotRequired["InvoiceService.UpcomingParamsIssuer"] + quantity: NotRequired[int] """ - The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + Quantity for this item. Defaults to 1. """ - on_behalf_of: NotRequired["Literal['']|str"] + tax_rates: NotRequired["Literal['']|List[str]"] """ - The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://stripe.com/docs/billing/invoices/connect) documentation for details. + The tax rates which apply to the item. When set, the `default_tax_rates` do not apply to this item. """ - schedule: NotRequired[str] + + class UpcomingParamsScheduleDetailsPhaseAddInvoiceItemDiscount(TypedDict): + coupon: NotRequired[str] """ - The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. + ID of the coupon to create a new discount for. """ - subscription: NotRequired[str] + discount: NotRequired[str] """ - The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a `subscription_items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_items` is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions. + ID of an existing discount on the object (or one of its ancestors) to reuse. """ - subscription_billing_cycle_anchor: NotRequired[ - "Literal['now', 'unchanged']|int" - ] + promotion_code: NotRequired[str] """ - For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. + ID of the promotion code to create a new discount for. """ - subscription_cancel_at: NotRequired["Literal['']|int"] + + class UpcomingParamsScheduleDetailsPhaseAddInvoiceItemPriceData(TypedDict): + currency: str """ - A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. + 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). """ - subscription_cancel_at_period_end: NotRequired[bool] + product: str """ - Boolean indicating whether this subscription should cancel at the end of the current period. + The ID of the product that this price will belong to. """ - subscription_cancel_now: NotRequired[bool] + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] """ - This simulates the subscription being canceled or expired immediately. + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. """ - subscription_default_tax_rates: NotRequired["Literal['']|List[str]"] + unit_amount: NotRequired[int] """ - If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. """ - subscription_items: NotRequired[ - List["InvoiceService.UpcomingParamsSubscriptionItem"] - ] + unit_amount_decimal: NotRequired[str] """ - A list of up to 20 subscription items, each with an attached price. + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - subscription_proration_behavior: NotRequired[ - Literal["always_invoice", "create_prorations", "none"] + + class UpcomingParamsScheduleDetailsPhaseAutomaticTax(TypedDict): + enabled: bool + """ + Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription. + """ + liability: NotRequired[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseAutomaticTaxLiability" ] """ - Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. """ - subscription_proration_date: NotRequired[int] + + class UpcomingParamsScheduleDetailsPhaseAutomaticTaxLiability(TypedDict): + account: NotRequired[str] """ - If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'. + The connected account being referenced when `type` is `account`. """ - subscription_resume_at: NotRequired[Literal["now"]] + type: Literal["account", "self"] """ - For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. + Type of the account referenced in the request. """ - subscription_start_date: NotRequired[int] + + class UpcomingParamsScheduleDetailsPhaseBillingThresholds(TypedDict): + amount_gte: NotRequired[int] """ - Date a subscription is intended to start (can be future or past). + Monetary threshold that triggers the subscription to advance to a new billing period """ - subscription_trial_end: NotRequired["Literal['now']|int"] + reset_billing_cycle_anchor: NotRequired[bool] """ - If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required. + Indicates if the `billing_cycle_anchor` should be reset when a threshold is reached. If true, `billing_cycle_anchor` will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged. """ - subscription_trial_from_plan: NotRequired[bool] + + class UpcomingParamsScheduleDetailsPhaseDiscount(TypedDict): + coupon: NotRequired[str] """ - Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `subscription_trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more. + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. """ - class UpcomingParamsAutomaticTax(TypedDict): - enabled: bool + class UpcomingParamsScheduleDetailsPhaseInvoiceSettings(TypedDict): + account_tax_ids: NotRequired["Literal['']|List[str]"] """ - Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified [tax rates](https://stripe.com/docs/api/tax_rates), negative amounts, or `tax_behavior=unspecified`) cannot be added to automatic tax invoices. + 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. """ - liability: NotRequired[ - "InvoiceService.UpcomingParamsAutomaticTaxLiability" + days_until_due: NotRequired[int] + """ + Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be `null` for subscription schedules where `billing=charge_automatically`. + """ + issuer: NotRequired[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseInvoiceSettingsIssuer" ] """ - The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. """ - class UpcomingParamsAutomaticTaxLiability(TypedDict): + class UpcomingParamsScheduleDetailsPhaseInvoiceSettingsIssuer(TypedDict): account: NotRequired[str] """ The connected account being referenced when `type` is `account`. @@ -919,277 +2505,223 @@ class UpcomingParamsAutomaticTaxLiability(TypedDict): Type of the account referenced in the request. """ - class UpcomingParamsCustomerDetails(TypedDict): - address: NotRequired[ - "Literal['']|InvoiceService.UpcomingParamsCustomerDetailsAddress" + class UpcomingParamsScheduleDetailsPhaseItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|InvoiceService.UpcomingParamsScheduleDetailsPhaseItemBillingThresholds" ] """ - The customer's address. + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. """ - shipping: NotRequired[ - "Literal['']|InvoiceService.UpcomingParamsCustomerDetailsShipping" + discounts: NotRequired[ + "Literal['']|List[InvoiceService.UpcomingParamsScheduleDetailsPhaseItemDiscount]" ] """ - The customer's shipping information. Appears on invoices emailed to this customer. + The coupons to redeem into discounts for the subscription item. """ - tax: NotRequired["InvoiceService.UpcomingParamsCustomerDetailsTax"] + metadata: NotRequired[Dict[str, str]] """ - Tax details about the customer. + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a configuration item. Metadata on a configuration item will update the underlying subscription item's `metadata` when the phase is entered, adding new keys and replacing existing keys. Individual keys in the subscription item's `metadata` can be unset by posting an empty value to them in the configuration item's `metadata`. To unset all keys in the subscription item's `metadata`, update the subscription item directly or unset every key individually from the configuration item's `metadata`. """ - tax_exempt: NotRequired[ - "Literal['']|Literal['exempt', 'none', 'reverse']" - ] + plan: NotRequired[str] """ - The customer's tax exemption. One of `none`, `exempt`, or `reverse`. + The plan ID to subscribe to. You may specify the same ID in `plan` and `price`. """ - tax_ids: NotRequired[ - List["InvoiceService.UpcomingParamsCustomerDetailsTaxId"] + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "InvoiceService.UpcomingParamsScheduleDetailsPhaseItemPriceData" ] """ - The customer's tax IDs. + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for the given price. Can be set only if the price's `usage_type` is `licensed` and not `metered`. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. """ - class UpcomingParamsCustomerDetailsAddress(TypedDict): - city: NotRequired[str] + class UpcomingParamsScheduleDetailsPhaseItemBillingThresholds(TypedDict): + usage_gte: int """ - City, district, suburb, town, or village. + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) """ - country: NotRequired[str] + + class UpcomingParamsScheduleDetailsPhaseItemDiscount(TypedDict): + coupon: NotRequired[str] """ - Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + ID of the coupon to create a new discount for. """ - line1: NotRequired[str] + discount: NotRequired[str] """ - Address line 1 (e.g., street, PO Box, or company name). + ID of an existing discount on the object (or one of its ancestors) to reuse. """ - line2: NotRequired[str] + promotion_code: NotRequired[str] """ - Address line 2 (e.g., apartment, suite, unit, or building). + ID of the promotion code to create a new discount for. """ - postal_code: NotRequired[str] + + class UpcomingParamsScheduleDetailsPhaseItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + recurring: "InvoiceService.UpcomingParamsScheduleDetailsPhaseItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] """ - ZIP or postal code. + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. """ - state: NotRequired[str] + unit_amount: NotRequired[int] """ - State, county, province, or region. + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. """ - - class UpcomingParamsCustomerDetailsShipping(TypedDict): - address: "InvoiceService.UpcomingParamsCustomerDetailsShippingAddress" + unit_amount_decimal: NotRequired[str] """ - Customer shipping address. + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - name: str + + class UpcomingParamsScheduleDetailsPhaseItemPriceDataRecurring(TypedDict): + interval: Literal["day", "month", "week", "year"] """ - Customer name. + Specifies billing frequency. Either `day`, `week`, `month` or `year`. """ - phone: NotRequired[str] + interval_count: NotRequired[int] """ - Customer phone (including extension). + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ - class UpcomingParamsCustomerDetailsShippingAddress(TypedDict): - city: NotRequired[str] + class UpcomingParamsScheduleDetailsPhaseTransferData(TypedDict): + amount_percent: NotRequired[float] """ - City, district, suburb, town, or village. + 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. """ - country: NotRequired[str] + destination: str """ - Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + ID of an existing, connected Stripe account. """ - line1: NotRequired[str] + + class UpcomingParamsSubscriptionDetails(TypedDict): + billing_cycle_anchor: NotRequired["Literal['now', 'unchanged']|int"] """ - Address line 1 (e.g., street, PO Box, or company name). + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. """ - line2: NotRequired[str] + cancel_at: NotRequired["Literal['']|int"] """ - Address line 2 (e.g., apartment, suite, unit, or building). + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. """ - postal_code: NotRequired[str] + cancel_at_period_end: NotRequired[bool] """ - ZIP or postal code. + Boolean indicating whether this subscription should cancel at the end of the current period. """ - state: NotRequired[str] + cancel_now: NotRequired[bool] """ - State, county, province, or region. + This simulates the subscription being canceled or expired immediately. """ - - class UpcomingParamsCustomerDetailsTax(TypedDict): - ip_address: NotRequired["Literal['']|str"] + default_tax_rates: NotRequired["Literal['']|List[str]"] """ - A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes. + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. """ - - class UpcomingParamsCustomerDetailsTaxId(TypedDict): - type: Literal[ - "ad_nrt", - "ae_trn", - "ar_cuit", - "au_abn", - "au_arn", - "bg_uic", - "bh_vat", - "bo_tin", - "br_cnpj", - "br_cpf", - "ca_bn", - "ca_gst_hst", - "ca_pst_bc", - "ca_pst_mb", - "ca_pst_sk", - "ca_qst", - "ch_vat", - "cl_tin", - "cn_tin", - "co_nit", - "cr_tin", - "do_rcn", - "ec_ruc", - "eg_tin", - "es_cif", - "eu_oss_vat", - "eu_vat", - "gb_vat", - "ge_vat", - "hk_br", - "hu_tin", - "id_npwp", - "il_vat", - "in_gst", - "is_vat", - "jp_cn", - "jp_rn", - "jp_trn", - "ke_pin", - "kr_brn", - "kz_bin", - "li_uid", - "mx_rfc", - "my_frp", - "my_itn", - "my_sst", - "ng_tin", - "no_vat", - "no_voec", - "nz_gst", - "om_vat", - "pe_ruc", - "ph_tin", - "ro_tin", - "rs_pib", - "ru_inn", - "ru_kpp", - "sa_vat", - "sg_gst", - "sg_uen", - "si_tin", - "sv_nit", - "th_vat", - "tr_tin", - "tw_vat", - "ua_vat", - "us_ein", - "uy_ruc", - "ve_rif", - "vn_tin", - "za_vat", + items: NotRequired[ + List["InvoiceService.UpcomingParamsSubscriptionDetailsItem"] ] """ - Type of the tax ID, one of `ad_nrt`, `ae_trn`, `ar_cuit`, `au_abn`, `au_arn`, `bg_uic`, `bh_vat`, `bo_tin`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_vat`, `cl_tin`, `cn_tin`, `co_nit`, `cr_tin`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `eu_oss_vat`, `eu_vat`, `gb_vat`, `ge_vat`, `hk_br`, `hu_tin`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kr_brn`, `kz_bin`, `li_uid`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `ng_tin`, `no_vat`, `no_voec`, `nz_gst`, `om_vat`, `pe_ruc`, `ph_tin`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sv_nit`, `th_vat`, `tr_tin`, `tw_vat`, `ua_vat`, `us_ein`, `uy_ruc`, `ve_rif`, `vn_tin`, or `za_vat` + A list of up to 20 subscription items, each with an attached price. """ - value: str + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] """ - Value of the tax ID. + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. """ - - class UpcomingParamsDiscount(TypedDict): - coupon: NotRequired[str] + proration_date: NotRequired[int] """ - ID of the coupon to create a new discount for. + If previewing an update to a subscription, and doing proration, `subscription_details.proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_details.items`, or `subscription_details.trial_end` are required. Also, `subscription_details.proration_behavior` cannot be set to 'none'. """ - discount: NotRequired[str] + resume_at: NotRequired[Literal["now"]] """ - ID of an existing discount on the object (or one of its ancestors) to reuse. + For paused subscriptions, setting `subscription_details.resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. """ - promotion_code: NotRequired[str] + start_date: NotRequired[int] """ - ID of the promotion code to create a new discount for. + Date a subscription is intended to start (can be future or past). """ - - class UpcomingParamsInvoiceItem(TypedDict): - amount: NotRequired[int] + trial_end: NotRequired["Literal['now']|int"] """ - The integer amount in cents (or local equivalent) of previewed invoice item. + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_details.items` or `subscription` is required. """ - currency: NotRequired[str] + + class UpcomingParamsSubscriptionDetailsItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|InvoiceService.UpcomingParamsSubscriptionDetailsItemBillingThresholds" + ] """ - 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). Only applicable to new invoice items. + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. """ - description: NotRequired[str] + clear_usage: NotRequired[bool] """ - An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + Delete all usage for a given subscription item. Allowed only when `deleted` is set to `true` and the current plan's `usage_type` is `metered`. """ - discountable: NotRequired[bool] + deleted: NotRequired[bool] """ - Explicitly controls whether discounts apply to this invoice item. Defaults to true, except for negative invoice items. + A flag that, if set to `true`, will delete the specified item. """ discounts: NotRequired[ - "Literal['']|List[InvoiceService.UpcomingParamsInvoiceItemDiscount]" + "Literal['']|List[InvoiceService.UpcomingParamsSubscriptionDetailsItemDiscount]" ] """ - The coupons to redeem into discounts for the invoice item in the preview. + The coupons to redeem into discounts for the subscription item. """ - invoiceitem: NotRequired[str] + id: NotRequired[str] """ - The ID of the invoice item to update in preview. If not specified, a new invoice item will be added to the preview of the upcoming invoice. + Subscription item to update. """ metadata: NotRequired["Literal['']|Dict[str, str]"] """ 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. """ - period: NotRequired["InvoiceService.UpcomingParamsInvoiceItemPeriod"] + plan: NotRequired[str] """ - The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + Plan ID for this item, as a string. """ price: NotRequired[str] """ - The ID of the price object. + The ID of the price object. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided. """ price_data: NotRequired[ - "InvoiceService.UpcomingParamsInvoiceItemPriceData" + "InvoiceService.UpcomingParamsSubscriptionDetailsItemPriceData" ] """ Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. """ quantity: NotRequired[int] """ - Non-negative integer. The quantity of units for the invoice item. - """ - tax_behavior: NotRequired[ - Literal["exclusive", "inclusive", "unspecified"] - ] - """ - Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. - """ - tax_code: NotRequired["Literal['']|str"] - """ - A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + Quantity for this item. """ tax_rates: NotRequired["Literal['']|List[str]"] """ - The tax rates that apply to the item. When set, any `default_tax_rates` do not apply to this item. - """ - unit_amount: NotRequired[int] - """ - The integer unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer's account, pass a negative unit_amount. + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. """ - unit_amount_decimal: NotRequired[str] + + class UpcomingParamsSubscriptionDetailsItemBillingThresholds(TypedDict): + usage_gte: int """ - Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) """ - class UpcomingParamsInvoiceItemDiscount(TypedDict): + class UpcomingParamsSubscriptionDetailsItemDiscount(TypedDict): coupon: NotRequired[str] """ ID of the coupon to create a new discount for. @@ -1203,17 +2735,7 @@ class UpcomingParamsInvoiceItemDiscount(TypedDict): ID of the promotion code to create a new discount for. """ - class UpcomingParamsInvoiceItemPeriod(TypedDict): - end: int - """ - The end of the period, which must be greater than or equal to the start. This value is inclusive. - """ - start: int - """ - The start of the period. This value is inclusive. - """ - - class UpcomingParamsInvoiceItemPriceData(TypedDict): + class UpcomingParamsSubscriptionDetailsItemPriceData(TypedDict): currency: str """ 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). @@ -1222,6 +2744,10 @@ class UpcomingParamsInvoiceItemPriceData(TypedDict): """ The ID of the product that this price will belong to. """ + recurring: "InvoiceService.UpcomingParamsSubscriptionDetailsItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ tax_behavior: NotRequired[ Literal["exclusive", "inclusive", "unspecified"] ] @@ -1237,14 +2763,14 @@ class UpcomingParamsInvoiceItemPriceData(TypedDict): Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. """ - class UpcomingParamsIssuer(TypedDict): - account: NotRequired[str] + class UpcomingParamsSubscriptionDetailsItemPriceDataRecurring(TypedDict): + interval: Literal["day", "month", "week", "year"] """ - The connected account being referenced when `type` is `account`. + Specifies billing frequency. Either `day`, `week`, `month` or `year`. """ - type: Literal["account", "self"] + interval_count: NotRequired[int] """ - Type of the account referenced in the request. + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ class UpcomingParamsSubscriptionItem(TypedDict): @@ -2491,3 +4017,51 @@ async def void_invoice_async( options=options, ), ) + + def create_preview( + self, + params: "InvoiceService.CreatePreviewParams" = {}, + options: RequestOptions = {}, + ) -> Invoice: + """ + At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice. + + Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer's discount. + + You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_details.proration_date value passed in the request. + """ + return cast( + Invoice, + self._request( + "post", + "/v1/invoices/create_preview", + api_mode="V1", + base_address="api", + params=params, + options=options, + ), + ) + + async def create_preview_async( + self, + params: "InvoiceService.CreatePreviewParams" = {}, + options: RequestOptions = {}, + ) -> Invoice: + """ + At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice. + + Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer's discount. + + You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_details.proration_date value passed in the request. + """ + return cast( + Invoice, + await self._request_async( + "post", + "/v1/invoices/create_preview", + api_mode="V1", + base_address="api", + params=params, + options=options, + ), + ) diff --git a/stripe/_invoice_upcoming_lines_service.py b/stripe/_invoice_upcoming_lines_service.py index a4e7d4c73..bd9ef2048 100644 --- a/stripe/_invoice_upcoming_lines_service.py +++ b/stripe/_invoice_upcoming_lines_service.py @@ -70,6 +70,12 @@ class ListParams(TypedDict): """ The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. """ + schedule_details: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetails" + ] + """ + The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields. + """ starting_after: NotRequired[str] """ A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. @@ -82,51 +88,57 @@ class ListParams(TypedDict): "Literal['now', 'unchanged']|int" ] """ - For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. This field has been deprecated and will be removed in a future API version. Use `subscription_details.billing_cycle_anchor` instead. """ subscription_cancel_at: NotRequired["Literal['']|int"] """ - A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_at` instead. """ subscription_cancel_at_period_end: NotRequired[bool] """ - Boolean indicating whether this subscription should cancel at the end of the current period. + Boolean indicating whether this subscription should cancel at the end of the current period. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_at_period_end` instead. """ subscription_cancel_now: NotRequired[bool] """ - This simulates the subscription being canceled or expired immediately. + This simulates the subscription being canceled or expired immediately. This field has been deprecated and will be removed in a future API version. Use `subscription_details.cancel_now` instead. """ subscription_default_tax_rates: NotRequired["Literal['']|List[str]"] """ - If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. This field has been deprecated and will be removed in a future API version. Use `subscription_details.default_tax_rates` instead. + """ + subscription_details: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsSubscriptionDetails" + ] + """ + The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields. """ subscription_items: NotRequired[ List["InvoiceUpcomingLinesService.ListParamsSubscriptionItem"] ] """ - A list of up to 20 subscription items, each with an attached price. + A list of up to 20 subscription items, each with an attached price. This field has been deprecated and will be removed in a future API version. Use `subscription_details.items` instead. """ subscription_proration_behavior: NotRequired[ Literal["always_invoice", "create_prorations", "none"] ] """ - Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. This field has been deprecated and will be removed in a future API version. Use `subscription_details.proration_behavior` instead. """ subscription_proration_date: NotRequired[int] """ - If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'. + If previewing an update to a subscription, and doing proration, `subscription_proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'. This field has been deprecated and will be removed in a future API version. Use `subscription_details.proration_date` instead. """ subscription_resume_at: NotRequired[Literal["now"]] """ - For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. + For paused subscriptions, setting `subscription_resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. This field has been deprecated and will be removed in a future API version. Use `subscription_details.resume_at` instead. """ subscription_start_date: NotRequired[int] """ - Date a subscription is intended to start (can be future or past). + Date a subscription is intended to start (can be future or past). This field has been deprecated and will be removed in a future API version. Use `subscription_details.start_date` instead. """ subscription_trial_end: NotRequired["Literal['now']|int"] """ - If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required. + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_items` or `subscription` is required. This field has been deprecated and will be removed in a future API version. Use `subscription_details.trial_end` instead. """ subscription_trial_from_plan: NotRequired[bool] """ @@ -487,6 +499,546 @@ class ListParamsIssuer(TypedDict): Type of the account referenced in the request. """ + class ListParamsScheduleDetails(TypedDict): + end_behavior: NotRequired[Literal["cancel", "release"]] + """ + Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running. `cancel` will end the subscription schedule and cancel the underlying subscription. + """ + phases: NotRequired[ + List["InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhase"] + ] + """ + List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the `end_date` of one phase will always equal the `start_date` of the next phase. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + In cases where the `schedule_details` params update the currently active phase, specifies if and how to prorate at the time of the request. + """ + + class ListParamsScheduleDetailsPhase(TypedDict): + add_invoice_items: NotRequired[ + List[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseAddInvoiceItem" + ] + ] + """ + A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. You may pass up to 20 items. + """ + application_fee_percent: NotRequired[float] + """ + 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 application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions). + """ + automatic_tax: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseAutomaticTax" + ] + """ + Automatic tax settings for this phase. + """ + billing_cycle_anchor: NotRequired[Literal["automatic", "phase_start"]] + """ + Can be set to `phase_start` to set the anchor to the start of the phase or `automatic` to automatically change it if needed. Cannot be set to `phase_start` if this phase specifies a trial. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle). + """ + billing_thresholds: NotRequired[ + "Literal['']|InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds. + """ + collection_method: NotRequired[ + Literal["charge_automatically", "send_invoice"] + ] + """ + Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically` on creation. + """ + coupon: NotRequired[str] + """ + The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. + """ + currency: NotRequired[str] + """ + 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). + """ + default_payment_method: NotRequired[str] + """ + ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer's invoice settings. + """ + default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will set the Subscription's [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates), which means they will be the Invoice's [`default_tax_rates`](https://stripe.com/docs/api/invoices/create#create_invoice-default_tax_rates) for any Invoices issued by the Subscription during this Phase. + """ + description: NotRequired["Literal['']|str"] + """ + Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseDiscount]" + ] + """ + The coupons to redeem into discounts for the schedule phase. If not specified, inherits the discount from the subscription's customer. Pass an empty string to avoid inheriting any discounts. + """ + end_date: NotRequired["int|Literal['now']"] + """ + The date at which this phase of the subscription schedule ends. If set, `iterations` must not be set. + """ + invoice_settings: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseInvoiceSettings" + ] + """ + All invoices will be billed using the specified settings. + """ + items: List[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseItem" + ] + """ + List of configuration items, each with an attached price, to apply during this phase of the subscription schedule. + """ + iterations: NotRequired[int] + """ + Integer representing the multiplier applied to the price interval. For example, `iterations=2` applied to a price with `interval=month` and `interval_count=3` results in a phase of duration `2 * 3 months = 6 months`. If set, `end_date` must not be set. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a phase. Metadata on a schedule's phase will update the underlying subscription's `metadata` when the phase is entered, adding new keys and replacing existing keys in the subscription's `metadata`. Individual keys in the subscription's `metadata` can be unset by posting an empty value to them in the phase's `metadata`. To unset all keys in the subscription's `metadata`, update the subscription directly or unset every key individually from the phase's `metadata`. + """ + on_behalf_of: NotRequired[str] + """ + The account on behalf of which to charge, for each of the associated subscription's invoices. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + Whether the subscription schedule will create [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when transitioning to this phase. The default value is `create_prorations`. This setting controls prorations when a phase is started asynchronously and it is persisted as a field on the phase. It's different from the request-level [proration_behavior](https://stripe.com/docs/api/subscription_schedules/update#update_subscription_schedule-proration_behavior) parameter which controls what happens if the update request affects the billing configuration of the current phase. + """ + start_date: NotRequired["int|Literal['now']"] + """ + The date at which this phase of the subscription schedule starts or `now`. Must be set on the first phase. + """ + transfer_data: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseTransferData" + ] + """ + The data with which to automatically create a Transfer for each of the associated subscription's invoices. + """ + trial: NotRequired[bool] + """ + If set to true the entire phase is counted as a trial and the customer will not be charged for any fees. + """ + trial_end: NotRequired["int|Literal['now']"] + """ + Sets the phase to trialing from the start date to this date. Must be before the phase end date, can not be combined with `trial` + """ + + class ListParamsScheduleDetailsPhaseAddInvoiceItem(TypedDict): + discounts: NotRequired[ + List[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseAddInvoiceItemDiscount" + ] + ] + """ + The coupons to redeem into discounts for the item. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseAddInvoiceItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for this item. Defaults to 1. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates which apply to the item. When set, the `default_tax_rates` do not apply to this item. + """ + + class ListParamsScheduleDetailsPhaseAddInvoiceItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class ListParamsScheduleDetailsPhaseAddInvoiceItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class ListParamsScheduleDetailsPhaseAutomaticTax(TypedDict): + enabled: bool + """ + Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription. + """ + liability: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseAutomaticTaxLiability" + ] + """ + The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. + """ + + class ListParamsScheduleDetailsPhaseAutomaticTaxLiability(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class ListParamsScheduleDetailsPhaseBillingThresholds(TypedDict): + amount_gte: NotRequired[int] + """ + Monetary threshold that triggers the subscription to advance to a new billing period + """ + reset_billing_cycle_anchor: NotRequired[bool] + """ + Indicates if the `billing_cycle_anchor` should be reset when a threshold is reached. If true, `billing_cycle_anchor` will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged. + """ + + class ListParamsScheduleDetailsPhaseDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class ListParamsScheduleDetailsPhaseInvoiceSettings(TypedDict): + account_tax_ids: NotRequired["Literal['']|List[str]"] + """ + 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. + """ + days_until_due: NotRequired[int] + """ + Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be `null` for subscription schedules where `billing=charge_automatically`. + """ + issuer: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseInvoiceSettingsIssuer" + ] + """ + The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. + """ + + class ListParamsScheduleDetailsPhaseInvoiceSettingsIssuer(TypedDict): + account: NotRequired[str] + """ + The connected account being referenced when `type` is `account`. + """ + type: Literal["account", "self"] + """ + Type of the account referenced in the request. + """ + + class ListParamsScheduleDetailsPhaseItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseItemBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseItemDiscount]" + ] + """ + The coupons to redeem into discounts for the subscription item. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to a configuration item. Metadata on a configuration item will update the underlying subscription item's `metadata` when the phase is entered, adding new keys and replacing existing keys. Individual keys in the subscription item's `metadata` can be unset by posting an empty value to them in the configuration item's `metadata`. To unset all keys in the subscription item's `metadata`, update the subscription item directly or unset every key individually from the configuration item's `metadata`. + """ + plan: NotRequired[str] + """ + The plan ID to subscribe to. You may specify the same ID in `plan` and `price`. + """ + price: NotRequired[str] + """ + The ID of the price object. + """ + price_data: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for the given price. Can be set only if the price's `usage_type` is `licensed` and not `metered`. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. + """ + + class ListParamsScheduleDetailsPhaseItemBillingThresholds(TypedDict): + usage_gte: int + """ + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) + """ + + class ListParamsScheduleDetailsPhaseItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class ListParamsScheduleDetailsPhaseItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + recurring: "InvoiceUpcomingLinesService.ListParamsScheduleDetailsPhaseItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class ListParamsScheduleDetailsPhaseItemPriceDataRecurring(TypedDict): + interval: Literal["day", "month", "week", "year"] + """ + Specifies billing frequency. Either `day`, `week`, `month` or `year`. + """ + interval_count: NotRequired[int] + """ + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). + """ + + class ListParamsScheduleDetailsPhaseTransferData(TypedDict): + amount_percent: NotRequired[float] + """ + 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. + """ + destination: str + """ + ID of an existing, connected Stripe account. + """ + + class ListParamsSubscriptionDetails(TypedDict): + billing_cycle_anchor: NotRequired["Literal['now', 'unchanged']|int"] + """ + For new subscriptions, a future timestamp to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). This is used to determine the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to `now` or `unchanged`. + """ + cancel_at: NotRequired["Literal['']|int"] + """ + A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. + """ + cancel_at_period_end: NotRequired[bool] + """ + Boolean indicating whether this subscription should cancel at the end of the current period. + """ + cancel_now: NotRequired[bool] + """ + This simulates the subscription being canceled or expired immediately. + """ + default_tax_rates: NotRequired["Literal['']|List[str]"] + """ + If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have `tax_rates` set. + """ + items: NotRequired[ + List[ + "InvoiceUpcomingLinesService.ListParamsSubscriptionDetailsItem" + ] + ] + """ + A list of up to 20 subscription items, each with an attached price. + """ + proration_behavior: NotRequired[ + Literal["always_invoice", "create_prorations", "none"] + ] + """ + Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. + """ + proration_date: NotRequired[int] + """ + If previewing an update to a subscription, and doing proration, `subscription_details.proration_date` forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, `subscription`, and one of `subscription_details.items`, or `subscription_details.trial_end` are required. Also, `subscription_details.proration_behavior` cannot be set to 'none'. + """ + resume_at: NotRequired[Literal["now"]] + """ + For paused subscriptions, setting `subscription_details.resume_at` to `now` will preview the invoice that will be generated if the subscription is resumed. + """ + start_date: NotRequired[int] + """ + Date a subscription is intended to start (can be future or past). + """ + trial_end: NotRequired["Literal['now']|int"] + """ + If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of `subscription_details.items` or `subscription` is required. + """ + + class ListParamsSubscriptionDetailsItem(TypedDict): + billing_thresholds: NotRequired[ + "Literal['']|InvoiceUpcomingLinesService.ListParamsSubscriptionDetailsItemBillingThresholds" + ] + """ + Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds. + """ + clear_usage: NotRequired[bool] + """ + Delete all usage for a given subscription item. Allowed only when `deleted` is set to `true` and the current plan's `usage_type` is `metered`. + """ + deleted: NotRequired[bool] + """ + A flag that, if set to `true`, will delete the specified item. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceUpcomingLinesService.ListParamsSubscriptionDetailsItemDiscount]" + ] + """ + The coupons to redeem into discounts for the subscription item. + """ + id: NotRequired[str] + """ + Subscription item to update. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + plan: NotRequired[str] + """ + Plan ID for this item, as a string. + """ + price: NotRequired[str] + """ + The ID of the price object. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided. + """ + price_data: NotRequired[ + "InvoiceUpcomingLinesService.ListParamsSubscriptionDetailsItemPriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. + """ + quantity: NotRequired[int] + """ + Quantity for this item. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates. + """ + + class ListParamsSubscriptionDetailsItemBillingThresholds(TypedDict): + usage_gte: int + """ + Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_thresholds-amount_gte)) + """ + + class ListParamsSubscriptionDetailsItemDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class ListParamsSubscriptionDetailsItemPriceData(TypedDict): + currency: str + """ + 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). + """ + product: str + """ + The ID of the product that this price will belong to. + """ + recurring: "InvoiceUpcomingLinesService.ListParamsSubscriptionDetailsItemPriceDataRecurring" + """ + The recurring components of a price such as `interval` and `interval_count`. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class ListParamsSubscriptionDetailsItemPriceDataRecurring(TypedDict): + interval: Literal["day", "month", "week", "year"] + """ + Specifies billing frequency. Either `day`, `week`, `month` or `year`. + """ + interval_count: NotRequired[int] + """ + The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). + """ + class ListParamsSubscriptionItem(TypedDict): billing_thresholds: NotRequired[ "Literal['']|InvoiceUpcomingLinesService.ListParamsSubscriptionItemBillingThresholds" From 807ba2e5be9d3061d750f2d1f8cbded05409b2b1 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Thu, 18 Apr 2024 17:18:05 +0000 Subject: [PATCH 8/9] Update generated code for v971 --- OPENAPI_VERSION | 2 +- stripe/checkout/_session.py | 29 +++++++++++++++++++++++++++++ stripe/checkout/_session_service.py | 17 +++++++++++++++++ 3 files changed, 47 insertions(+), 1 deletion(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 6031d9a63..481ad6d30 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v969 \ No newline at end of file +v971 \ No newline at end of file diff --git a/stripe/checkout/_session.py b/stripe/checkout/_session.py index d17dfd272..f4a958c37 100644 --- a/stripe/checkout/_session.py +++ b/stripe/checkout/_session.py @@ -824,6 +824,16 @@ class Link(StripeObject): When processing card payments, Stripe also uses `setup_future_usage` to dynamically optimize your payment flow and comply with regional legislation and network rules, such as [SCA](https://stripe.com/docs/strong-customer-authentication). """ + class Mobilepay(StripeObject): + setup_future_usage: Optional[Literal["none"]] + """ + Indicates that you intend to make future payments with this PaymentIntent's payment method. + + Providing this parameter will [attach the payment method](https://stripe.com/docs/payments/save-during-payment) to the PaymentIntent's Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete. If no Customer was provided, the payment method can still be [attached](https://stripe.com/docs/api/payment_methods/attach) to a Customer after the transaction completes. + + When processing card payments, Stripe also uses `setup_future_usage` to dynamically optimize your payment flow and comply with regional legislation and network rules, such as [SCA](https://stripe.com/docs/strong-customer-authentication). + """ + class Oxxo(StripeObject): expires_after_days: int """ @@ -982,6 +992,7 @@ class FinancialConnections(StripeObject): klarna: Optional[Klarna] konbini: Optional[Konbini] link: Optional[Link] + mobilepay: Optional[Mobilepay] oxxo: Optional[Oxxo] p24: Optional[P24] paynow: Optional[Paynow] @@ -1013,6 +1024,7 @@ class FinancialConnections(StripeObject): "klarna": Klarna, "konbini": Konbini, "link": Link, + "mobilepay": Mobilepay, "oxxo": Oxxo, "p24": P24, "paynow": Paynow, @@ -1711,6 +1723,7 @@ class CreateParams(RequestOptions): "klarna", "konbini", "link", + "mobilepay", "oxxo", "p24", "paynow", @@ -2453,6 +2466,12 @@ class CreateParamsPaymentMethodOptions(TypedDict): """ contains details about the Link payment method options. """ + mobilepay: NotRequired[ + "Session.CreateParamsPaymentMethodOptionsMobilepay" + ] + """ + contains details about the Mobilepay payment method options. + """ oxxo: NotRequired["Session.CreateParamsPaymentMethodOptionsOxxo"] """ contains details about the OXXO payment method options. @@ -2847,6 +2866,16 @@ class CreateParamsPaymentMethodOptionsLink(TypedDict): When processing card payments, Stripe also uses `setup_future_usage` to dynamically optimize your payment flow and comply with regional legislation and network rules, such as [SCA](https://stripe.com/docs/strong-customer-authentication). """ + class CreateParamsPaymentMethodOptionsMobilepay(TypedDict): + setup_future_usage: NotRequired[Literal["none"]] + """ + Indicates that you intend to make future payments with this PaymentIntent's payment method. + + Providing this parameter will [attach the payment method](https://stripe.com/docs/payments/save-during-payment) to the PaymentIntent's Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete. If no Customer was provided, the payment method can still be [attached](https://stripe.com/docs/api/payment_methods/attach) to a Customer after the transaction completes. + + When processing card payments, Stripe also uses `setup_future_usage` to dynamically optimize your payment flow and comply with regional legislation and network rules, such as [SCA](https://stripe.com/docs/strong-customer-authentication). + """ + class CreateParamsPaymentMethodOptionsOxxo(TypedDict): expires_after_days: NotRequired[int] """ diff --git a/stripe/checkout/_session_service.py b/stripe/checkout/_session_service.py index 6edb1dbf3..38e2d1460 100644 --- a/stripe/checkout/_session_service.py +++ b/stripe/checkout/_session_service.py @@ -243,6 +243,7 @@ class CreateParams(TypedDict): "klarna", "konbini", "link", + "mobilepay", "oxxo", "p24", "paynow", @@ -1021,6 +1022,12 @@ class CreateParamsPaymentMethodOptions(TypedDict): """ contains details about the Link payment method options. """ + mobilepay: NotRequired[ + "SessionService.CreateParamsPaymentMethodOptionsMobilepay" + ] + """ + contains details about the Mobilepay payment method options. + """ oxxo: NotRequired[ "SessionService.CreateParamsPaymentMethodOptionsOxxo" ] @@ -1425,6 +1432,16 @@ class CreateParamsPaymentMethodOptionsLink(TypedDict): When processing card payments, Stripe also uses `setup_future_usage` to dynamically optimize your payment flow and comply with regional legislation and network rules, such as [SCA](https://stripe.com/docs/strong-customer-authentication). """ + class CreateParamsPaymentMethodOptionsMobilepay(TypedDict): + setup_future_usage: NotRequired[Literal["none"]] + """ + Indicates that you intend to make future payments with this PaymentIntent's payment method. + + Providing this parameter will [attach the payment method](https://stripe.com/docs/payments/save-during-payment) to the PaymentIntent's Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete. If no Customer was provided, the payment method can still be [attached](https://stripe.com/docs/api/payment_methods/attach) to a Customer after the transaction completes. + + When processing card payments, Stripe also uses `setup_future_usage` to dynamically optimize your payment flow and comply with regional legislation and network rules, such as [SCA](https://stripe.com/docs/strong-customer-authentication). + """ + class CreateParamsPaymentMethodOptionsOxxo(TypedDict): expires_after_days: NotRequired[int] """ From 1019bba3639ccbb2ec314a964688a16fbba638d5 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Thu, 18 Apr 2024 18:20:35 +0000 Subject: [PATCH 9/9] Update generated code for v972 --- OPENAPI_VERSION | 2 +- stripe/billing/_meter_event.py | 2 +- stripe/billing/_meter_event_service.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 481ad6d30..e0b273508 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v971 \ No newline at end of file +v972 \ No newline at end of file diff --git a/stripe/billing/_meter_event.py b/stripe/billing/_meter_event.py index bd49da21f..aa247a91a 100644 --- a/stripe/billing/_meter_event.py +++ b/stripe/billing/_meter_event.py @@ -35,7 +35,7 @@ class CreateParams(RequestOptions): """ timestamp: NotRequired[int] """ - The time of the event. Measured in seconds since the Unix epoch. Defaults to current timestamp if not specified. + The time of the event. Measured in seconds since the Unix epoch. Must be within the past 35 calendar days or up to 5 minutes in the future. Defaults to current timestamp if not specified. """ created: int diff --git a/stripe/billing/_meter_event_service.py b/stripe/billing/_meter_event_service.py index c2e72e1de..a8ad2beba 100644 --- a/stripe/billing/_meter_event_service.py +++ b/stripe/billing/_meter_event_service.py @@ -27,7 +27,7 @@ class CreateParams(TypedDict): """ timestamp: NotRequired[int] """ - The time of the event. Measured in seconds since the Unix epoch. Defaults to current timestamp if not specified. + The time of the event. Measured in seconds since the Unix epoch. Must be within the past 35 calendar days or up to 5 minutes in the future. Defaults to current timestamp if not specified. """ def create(