From dc577065b0bb47a1b9a01491ebfd7cfdcf8e15d2 Mon Sep 17 00:00:00 2001 From: "stripe-openapi[bot]" <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Thu, 18 Apr 2024 14:17:57 -0700 Subject: [PATCH 01/21] Update generated code (#1305) * Update generated code for v963 * Update generated code for v964 * Update generated code for v966 * Update generated code for v967 * Update generated code for v967 * Update generated code for v968 * Update generated code for v969 * Update generated code for v971 * Update generated code for v972 --------- Co-authored-by: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> --- OPENAPI_VERSION | 2 +- stripe/_confirmation_token.py | 6 + stripe/_customer.py | 6 + stripe/_customer_payment_method_service.py | 6 + stripe/_invoice.py | 3764 +++++++++++++---- stripe/_invoice_service.py | 2260 ++++++++-- stripe/_invoice_upcoming_lines_service.py | 574 ++- 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 + stripe/billing/_meter.py | 20 +- stripe/billing/_meter_event.py | 6 +- stripe/billing/_meter_event_service.py | 4 +- stripe/billing/_meter_event_summary.py | 8 +- .../billing/_meter_event_summary_service.py | 4 +- stripe/billing/_meter_service.py | 8 +- stripe/checkout/_session.py | 78 + stripe/checkout/_session_service.py | 49 + stripe/issuing/_authorization.py | 4 +- stripe/issuing/_transaction.py | 10 +- .../_confirmation_token_service.py | 6 + .../issuing/_authorization_service.py | 4 +- .../issuing/_transaction_service.py | 8 +- 26 files changed, 5706 insertions(+), 1217 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index ea2fb0ba1..e0b273508 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v961 \ No newline at end of file +v972 \ 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/_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" 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/billing/_meter.py b/stripe/billing/_meter.py index bc87cb308..a6d0221b6 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): @@ -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): @@ -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..aa247a91a 100644 --- a/stripe/billing/_meter_event.py +++ b/stripe/billing/_meter_event.py @@ -31,11 +31,11 @@ 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] """ - 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 @@ -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..a8ad2beba 100644 --- a/stripe/billing/_meter_event_service.py +++ b/stripe/billing/_meter_event_service.py @@ -23,11 +23,11 @@ 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] """ - 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( 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..a2e78e36a 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): @@ -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): diff --git a/stripe/checkout/_session.py b/stripe/checkout/_session.py index 561a67be3..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, @@ -1031,6 +1043,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 +1687,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" ] @@ -1693,6 +1723,7 @@ class CreateParams(RequestOptions): "klarna", "konbini", "link", + "mobilepay", "oxxo", "p24", "paynow", @@ -1743,6 +1774,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 +2363,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" @@ -2421,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. @@ -2815,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] """ @@ -3017,6 +3078,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 +3894,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 +4293,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..38e2d1460 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" ] @@ -237,6 +243,7 @@ class CreateParams(TypedDict): "klarna", "konbini", "link", + "mobilepay", "oxxo", "p24", "paynow", @@ -287,6 +294,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 +897,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" @@ -1001,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" ] @@ -1405,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] """ @@ -1607,6 +1644,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] """ 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/_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" ] 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 40e7e587d70fb145ed2ade87c3178f14701546d3 Mon Sep 17 00:00:00 2001 From: Ramya Rao Date: Thu, 18 Apr 2024 14:29:49 -0700 Subject: [PATCH 02/21] Bump version to 9.3.0 --- CHANGELOG.md | 31 ++++++++++++++++++++++--------- VERSION | 2 +- stripe/_version.py | 2 +- 3 files changed, 24 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index df07bcfc6..51b2495b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,14 +1,27 @@ +## 9.3.0 - 2024-04-18 +* [#1305](https://github.com/stripe/stripe-python/pull/1305) Update generated code + * Add support for `allow_redisplay` on parameter classes `stripe.ConfirmationToken.CreateParamsPaymentMethodData`, `stripe.Customer.ListPaymentMethodsParams`, `stripe.PaymentIntent.ConfirmParamsPaymentMethodData`, `stripe.PaymentIntent.CreateParamsPaymentMethodData`, `stripe.PaymentIntent.ModifyParamsPaymentMethodData`, `stripe.PaymentMethod.CreateParams`, `stripe.PaymentMethod.ModifyParams`, `stripe.SetupIntent.ConfirmParamsPaymentMethodData`, `stripe.SetupIntent.CreateParamsPaymentMethodData`, and `stripe.SetupIntent.ModifyParamsPaymentMethodData` + * Add support for `schedule_details` on parameter classes `stripe.Invoice.UpcomingLinesParams` and `stripe.Invoice.UpcomingParams` + * Add support for `subscription_details` on parameter classes `stripe.Invoice.UpcomingLinesParams` and `stripe.Invoice.UpcomingParams` + * Add support for `create_preview` on resource `stripe.Invoice` + * Add support for `payment_method_data` on parameter class `stripe.checkout.Session.CreateParams` + * Add support for `saved_payment_method_options` on parameter class `stripe.checkout.Session.CreateParams` and resource `stripe.checkout.Session` + * Add support for `mobilepay` on parameter class `stripe.checkout.Session.CreateParamsPaymentMethodOptions` and resource class `stripe.checkout.Session.PaymentMethodOptions` + * Add support for `mobilepay` on enum `stripe.checkout.Session.CreateParams.payment_method_types` + * Add support for `other` on enums `stripe.issuing.Authorization.CaptureParamsPurchaseDetailsFuel.unit`, `stripe.issuing.Transaction.CreateForceCaptureParamsPurchaseDetailsFuel.unit`, and `stripe.issuing.Transaction.CreateUnlinkedRefundParamsPurchaseDetailsFuel.unit` +* [#1306](https://github.com/stripe/stripe-python/pull/1306) Update `Quote.pdf()` to use the right base address i.e. files.stripe.com instead of api.stripe.com. Fixes [#1303](https://github.com/stripe/stripe-python/issues/1303) + ## 9.2.0 - 2024-04-16 * [#1301](https://github.com/stripe/stripe-python/pull/1301) Update generated code - * Add support for `balances` on resource class `stripe.AccountSession.Components` and parameter class `stripe.AccountSession.CreateParamsComponents` - * Add support for `payouts_list` on resource class `stripe.AccountSession.Components` and parameter class `stripe.AccountSession.CreateParamsComponents` - * Add support for `capture_method` on parameter classes `stripe.PaymentIntent.ConfirmParamsPaymentMethodOptionsRevolutPay`, `stripe.PaymentIntent.CreateParamsPaymentMethodOptionsRevolutPay`, and `stripe.PaymentIntent.ModifyParamsPaymentMethodOptionsRevolutPay` and resource class `stripe.PaymentIntent.PaymentMethodOptions.RevolutPay` - * Add support for `swish` on parameter classes `stripe.PaymentMethodConfiguration.CreateParams` and `stripe.PaymentMethodConfiguration.ModifyParams` and resource `stripe.PaymentMethodConfiguration` - * Add support for resource `stripe.entitlements.ActiveEntitlementSummary` - * Remove support for `config` on parameter class `stripe.forwarding.Request.CreateParams` and resource `stripe.forwarding.Request`. This field is no longer used by the Forwarding Request API. - * Change type of fields `stripe.AccountSession.Components.PaymentDetails.Features` and `stripe.AccountSession.Components.Payments.Features` from `Optional[bool]` to `bool` of `destination_on_behalf_of_charge_management` - * Change type of field `stripe.billing.MeterEvent.CreateParams` from `int` to `NotRequired[int]` of `timestamp` - * Add support for `entitlements.active_entitlement_summary.updated` on enums `stripe.Event.type`, `stripe.WebhookEndpoint.CreateParams.enabled_events`, and `stripe.WebhookEndpoint.ModifyParams.enabled_events` + * Add support for `balances` on resource class `stripe.AccountSession.Components` and parameter class `stripe.AccountSession.CreateParamsComponents` + * Add support for `payouts_list` on resource class `stripe.AccountSession.Components` and parameter class `stripe.AccountSession.CreateParamsComponents` + * Add support for `capture_method` on parameter classes `stripe.PaymentIntent.ConfirmParamsPaymentMethodOptionsRevolutPay`, `stripe.PaymentIntent.CreateParamsPaymentMethodOptionsRevolutPay`, and `stripe.PaymentIntent.ModifyParamsPaymentMethodOptionsRevolutPay` and resource class `stripe.PaymentIntent.PaymentMethodOptions.RevolutPay` + * Add support for `swish` on parameter classes `stripe.PaymentMethodConfiguration.CreateParams` and `stripe.PaymentMethodConfiguration.ModifyParams` and resource `stripe.PaymentMethodConfiguration` + * Add support for resource `stripe.entitlements.ActiveEntitlementSummary` + * Remove support for `config` on parameter class `stripe.forwarding.Request.CreateParams` and resource `stripe.forwarding.Request`. This field is no longer used by the Forwarding Request API. + * Change type of fields `stripe.AccountSession.Components.PaymentDetails.Features` and `stripe.AccountSession.Components.Payments.Features` from `Optional[bool]` to `bool` of `destination_on_behalf_of_charge_management` + * Change type of field `stripe.billing.MeterEvent.CreateParams` from `int` to `NotRequired[int]` of `timestamp` + * Add support for `entitlements.active_entitlement_summary.updated` on enums `stripe.Event.type`, `stripe.WebhookEndpoint.CreateParams.enabled_events`, and `stripe.WebhookEndpoint.ModifyParams.enabled_events` ## 9.1.0 - 2024-04-11 * [#1300](https://github.com/stripe/stripe-python/pull/1300) Update generated code diff --git a/VERSION b/VERSION index deeb3d66e..b13d146a7 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -9.2.0 +9.3.0 diff --git a/stripe/_version.py b/stripe/_version.py index cb44d32ab..057c95a46 100644 --- a/stripe/_version.py +++ b/stripe/_version.py @@ -1 +1 @@ -VERSION = "9.2.0" +VERSION = "9.3.0" From 51ae1cd5db18267442de4098b820503c9c4680a3 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Fri, 19 Apr 2024 23:18:19 +0000 Subject: [PATCH 03/21] Update generated code for v974 --- OPENAPI_VERSION | 2 +- stripe/_invoice.py | 4 ++-- stripe/_invoice_line_item.py | 4 ++-- stripe/_invoice_line_item_service.py | 2 +- stripe/_invoice_service.py | 4 ++-- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index e0b273508..afb443dc4 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v972 \ No newline at end of file +v974 \ No newline at end of file diff --git a/stripe/_invoice.py b/stripe/_invoice.py index 5c4f3ff79..1a647b4e2 100644 --- a/stripe/_invoice.py +++ b/stripe/_invoice.py @@ -8781,7 +8781,7 @@ class UpdateLinesParams(RequestOptions): """ 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`. + 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`. For `type=recurring` line items, the incoming metadata specified on the request is directly used to set this value, in contrast to `type=invoiceitem` line items, where any existing metadata on the invoice line is merged with the incoming data. """ lines: List["Invoice.UpdateLinesParamsLine"] """ @@ -8817,7 +8817,7 @@ class UpdateLinesParamsLine(TypedDict): """ 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`. + 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`. For `type=recurring` line items, the incoming metadata specified on the request is directly used to set this value, in contrast to `type=invoiceitem` line items, where any existing metadata on the invoice line is merged with the incoming data. """ period: NotRequired["Invoice.UpdateLinesParamsLinePeriod"] """ diff --git a/stripe/_invoice_line_item.py b/stripe/_invoice_line_item.py index a0964ac8e..ecc9dbc96 100644 --- a/stripe/_invoice_line_item.py +++ b/stripe/_invoice_line_item.py @@ -144,7 +144,7 @@ class ModifyParams(RequestOptions): """ 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`. + 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`. For `type=recurring` line items, the incoming metadata specified on the request is directly used to set this value, in contrast to `type=invoiceitem` line items, where any existing metadata on the invoice line is merged with the incoming data. """ period: NotRequired["InvoiceLineItem.ModifyParamsPeriod"] """ @@ -400,7 +400,7 @@ class ModifyParamsTaxAmountTaxRateData(TypedDict): """ metadata: 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. Note that for line items with `type=subscription` this will reflect the metadata of the subscription that caused the line item to be created. + 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. Note that for line items with `type=subscription`, `metadata` reflects the current metadata from the subscription associated with the line item, unless the invoice line was directly updated with different metadata after creation. """ object: Literal["line_item"] """ diff --git a/stripe/_invoice_line_item_service.py b/stripe/_invoice_line_item_service.py index 795b93234..a12b08c24 100644 --- a/stripe/_invoice_line_item_service.py +++ b/stripe/_invoice_line_item_service.py @@ -57,7 +57,7 @@ class UpdateParams(TypedDict): """ 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`. + 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`. For `type=recurring` line items, the incoming metadata specified on the request is directly used to set this value, in contrast to `type=invoiceitem` line items, where any existing metadata on the invoice line is merged with the incoming data. """ period: NotRequired["InvoiceLineItemService.UpdateParamsPeriod"] """ diff --git a/stripe/_invoice_service.py b/stripe/_invoice_service.py index 3abb63445..70155031e 100644 --- a/stripe/_invoice_service.py +++ b/stripe/_invoice_service.py @@ -5032,7 +5032,7 @@ class UpdateLinesParams(TypedDict): """ 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`. + 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`. For `type=recurring` line items, the incoming metadata specified on the request is directly used to set this value, in contrast to `type=invoiceitem` line items, where any existing metadata on the invoice line is merged with the incoming data. """ lines: List["InvoiceService.UpdateLinesParamsLine"] """ @@ -5068,7 +5068,7 @@ class UpdateLinesParamsLine(TypedDict): """ 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`. + 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`. For `type=recurring` line items, the incoming metadata specified on the request is directly used to set this value, in contrast to `type=invoiceitem` line items, where any existing metadata on the invoice line is merged with the incoming data. """ period: NotRequired["InvoiceService.UpdateLinesParamsLinePeriod"] """ From b4bd8bc00cadab15e786146b20bf57981fb09c88 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Fri, 19 Apr 2024 23:47:22 +0000 Subject: [PATCH 04/21] Update generated code for v975 --- OPENAPI_VERSION | 2 +- stripe/_payment_method_configuration.py | 12 ++++++++++++ stripe/_payment_method_configuration_service.py | 12 ++++++++++++ 3 files changed, 25 insertions(+), 1 deletion(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index afb443dc4..32eb2fbfa 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v974 \ No newline at end of file +v975 \ No newline at end of file diff --git a/stripe/_payment_method_configuration.py b/stripe/_payment_method_configuration.py index 187921af7..a4f3d27ac 100644 --- a/stripe/_payment_method_configuration.py +++ b/stripe/_payment_method_configuration.py @@ -1628,10 +1628,22 @@ class ListParams(RequestOptions): """ The Connect application to filter by. """ + 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. + """ class ModifyParams(RequestOptions): acss_debit: NotRequired[ diff --git a/stripe/_payment_method_configuration_service.py b/stripe/_payment_method_configuration_service.py index 3545bdfe2..15c48ace8 100644 --- a/stripe/_payment_method_configuration_service.py +++ b/stripe/_payment_method_configuration_service.py @@ -791,10 +791,22 @@ class ListParams(TypedDict): """ The Connect application to filter by. """ + 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. + """ class RetrieveParams(TypedDict): expand: NotRequired[List[str]] From 9662514dd22ca10555a5e8835d119079f2c55a95 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Mon, 22 Apr 2024 16:08:55 +0000 Subject: [PATCH 05/21] Update generated code for v976 --- OPENAPI_VERSION | 2 +- stripe/identity/_verification_session.py | 52 +------------------ .../identity/_verification_session_service.py | 52 +------------------ 3 files changed, 5 insertions(+), 101 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 32eb2fbfa..9eaeb566b 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v975 \ No newline at end of file +v976 \ No newline at end of file diff --git a/stripe/identity/_verification_session.py b/stripe/identity/_verification_session.py index 85e8fca6a..333126995 100644 --- a/stripe/identity/_verification_session.py +++ b/stripe/identity/_verification_session.py @@ -249,11 +249,11 @@ class CreateParams(RequestOptions): """ type: NotRequired[Literal["document", "id_number"]] """ - The type of [verification check](https://stripe.com/docs/identity/verification-checks) to be performed. + The type of [verification check](https://stripe.com/docs/identity/verification-checks) to be performed. You must provide a `type` if not passing `verification_flow`. """ verification_flow: NotRequired[str] """ - The ID of a Verification Flow from the Dashboard. + The ID of a Verification Flow from the Dashboard. See https://docs.stripe.com/identity/verification-flows. """ class CreateParamsOptions(TypedDict): @@ -263,18 +263,6 @@ class CreateParamsOptions(TypedDict): """ Options that apply to the [document check](https://stripe.com/docs/identity/verification-checks?type=document). """ - email: NotRequired[ - "Literal['']|VerificationSession.CreateParamsOptionsEmail" - ] - """ - Options that apply to the email check. - """ - phone: NotRequired[ - "Literal['']|VerificationSession.CreateParamsOptionsPhone" - ] - """ - Options that apply to the phone check. - """ class CreateParamsOptionsDocument(TypedDict): allowed_types: NotRequired[ @@ -296,18 +284,6 @@ class CreateParamsOptionsDocument(TypedDict): Capture a face image and perform a [selfie check](https://stripe.com/docs/identity/verification-checks?type=selfie) comparing a photo ID and a picture of your user's face. [Learn more](https://stripe.com/docs/identity/selfie). """ - class CreateParamsOptionsEmail(TypedDict): - require_verification: NotRequired[bool] - """ - Request one time password verification of `provided_details.email`. - """ - - class CreateParamsOptionsPhone(TypedDict): - require_verification: NotRequired[bool] - """ - Request one time password verification of `provided_details.phone`. - """ - class CreateParamsProvidedDetails(TypedDict): email: NotRequired[str] """ @@ -399,18 +375,6 @@ class ModifyParamsOptions(TypedDict): """ Options that apply to the [document check](https://stripe.com/docs/identity/verification-checks?type=document). """ - email: NotRequired[ - "Literal['']|VerificationSession.ModifyParamsOptionsEmail" - ] - """ - Options that apply to the email check. - """ - phone: NotRequired[ - "Literal['']|VerificationSession.ModifyParamsOptionsPhone" - ] - """ - Options that apply to the phone check. - """ class ModifyParamsOptionsDocument(TypedDict): allowed_types: NotRequired[ @@ -432,18 +396,6 @@ class ModifyParamsOptionsDocument(TypedDict): Capture a face image and perform a [selfie check](https://stripe.com/docs/identity/verification-checks?type=selfie) comparing a photo ID and a picture of your user's face. [Learn more](https://stripe.com/docs/identity/selfie). """ - class ModifyParamsOptionsEmail(TypedDict): - require_verification: NotRequired[bool] - """ - Request one time password verification of `provided_details.email`. - """ - - class ModifyParamsOptionsPhone(TypedDict): - require_verification: NotRequired[bool] - """ - Request one time password verification of `provided_details.phone`. - """ - class ModifyParamsProvidedDetails(TypedDict): email: NotRequired[str] """ diff --git a/stripe/identity/_verification_session_service.py b/stripe/identity/_verification_session_service.py index 81e30c25c..f615b461e 100644 --- a/stripe/identity/_verification_session_service.py +++ b/stripe/identity/_verification_session_service.py @@ -45,11 +45,11 @@ class CreateParams(TypedDict): """ type: NotRequired[Literal["document", "id_number"]] """ - The type of [verification check](https://stripe.com/docs/identity/verification-checks) to be performed. + The type of [verification check](https://stripe.com/docs/identity/verification-checks) to be performed. You must provide a `type` if not passing `verification_flow`. """ verification_flow: NotRequired[str] """ - The ID of a Verification Flow from the Dashboard. + The ID of a Verification Flow from the Dashboard. See https://docs.stripe.com/identity/verification-flows. """ class CreateParamsOptions(TypedDict): @@ -59,18 +59,6 @@ class CreateParamsOptions(TypedDict): """ Options that apply to the [document check](https://stripe.com/docs/identity/verification-checks?type=document). """ - email: NotRequired[ - "Literal['']|VerificationSessionService.CreateParamsOptionsEmail" - ] - """ - Options that apply to the email check. - """ - phone: NotRequired[ - "Literal['']|VerificationSessionService.CreateParamsOptionsPhone" - ] - """ - Options that apply to the phone check. - """ class CreateParamsOptionsDocument(TypedDict): allowed_types: NotRequired[ @@ -92,18 +80,6 @@ class CreateParamsOptionsDocument(TypedDict): Capture a face image and perform a [selfie check](https://stripe.com/docs/identity/verification-checks?type=selfie) comparing a photo ID and a picture of your user's face. [Learn more](https://stripe.com/docs/identity/selfie). """ - class CreateParamsOptionsEmail(TypedDict): - require_verification: NotRequired[bool] - """ - Request one time password verification of `provided_details.email`. - """ - - class CreateParamsOptionsPhone(TypedDict): - require_verification: NotRequired[bool] - """ - Request one time password verification of `provided_details.phone`. - """ - class CreateParamsProvidedDetails(TypedDict): email: NotRequired[str] """ @@ -209,18 +185,6 @@ class UpdateParamsOptions(TypedDict): """ Options that apply to the [document check](https://stripe.com/docs/identity/verification-checks?type=document). """ - email: NotRequired[ - "Literal['']|VerificationSessionService.UpdateParamsOptionsEmail" - ] - """ - Options that apply to the email check. - """ - phone: NotRequired[ - "Literal['']|VerificationSessionService.UpdateParamsOptionsPhone" - ] - """ - Options that apply to the phone check. - """ class UpdateParamsOptionsDocument(TypedDict): allowed_types: NotRequired[ @@ -242,18 +206,6 @@ class UpdateParamsOptionsDocument(TypedDict): Capture a face image and perform a [selfie check](https://stripe.com/docs/identity/verification-checks?type=selfie) comparing a photo ID and a picture of your user's face. [Learn more](https://stripe.com/docs/identity/selfie). """ - class UpdateParamsOptionsEmail(TypedDict): - require_verification: NotRequired[bool] - """ - Request one time password verification of `provided_details.email`. - """ - - class UpdateParamsOptionsPhone(TypedDict): - require_verification: NotRequired[bool] - """ - Request one time password verification of `provided_details.phone`. - """ - class UpdateParamsProvidedDetails(TypedDict): email: NotRequired[str] """ From 2a8836143ed8adf4e693880a4150163e5f89551a Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Mon, 22 Apr 2024 17:35:51 +0000 Subject: [PATCH 06/21] Update generated code for v977 --- OPENAPI_VERSION | 2 +- stripe/_confirmation_token.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 9eaeb566b..e0fe92557 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v976 \ No newline at end of file +v977 \ No newline at end of file diff --git a/stripe/_confirmation_token.py b/stripe/_confirmation_token.py index 98ac3689f..46c770e89 100644 --- a/stripe/_confirmation_token.py +++ b/stripe/_confirmation_token.py @@ -1957,7 +1957,7 @@ class RetrieveParams(RequestOptions): """ expires_at: Optional[int] """ - Time at which this ConfirmationToken expires and can no longer be used to confirm a PaymentIntent or SetupIntent. This is set to null once this ConfirmationToken has been used. + Time at which this ConfirmationToken expires and can no longer be used to confirm a PaymentIntent or SetupIntent. """ id: str """ From 7cce7568f24029dd209ecb17993ce700f421a3fd Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 22 Apr 2024 18:04:39 +0000 Subject: [PATCH 07/21] Bump aiohttp from 3.9.2 to 3.9.4 (#1307) Bumps [aiohttp](https://github.com/aio-libs/aiohttp) from 3.9.2 to 3.9.4. - [Release notes](https://github.com/aio-libs/aiohttp/releases) - [Changelog](https://github.com/aio-libs/aiohttp/blob/master/CHANGES.rst) - [Commits](https://github.com/aio-libs/aiohttp/compare/v3.9.2...v3.9.4) --- updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: helenye-stripe <111009531+helenye-stripe@users.noreply.github.com> --- test-requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test-requirements.txt b/test-requirements.txt index 843756dad..f2e9a43ba 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -5,7 +5,7 @@ httpx == 0.22.0; python_version == "3.6" httpx >= 0.24.1; python_version == "3.7" httpx >= 0.27.0; python_version >= "3.8" aiohttp == 3.8.6; python_version <= "3.7" -aiohttp == 3.9.2; python_version > "3.7" +aiohttp == 3.9.4; python_version > "3.7" anyio[trio] == 3.6.2 pytest-cov >= 2.8.1, < 2.11.0 From 7decbc00f7f08875249af7182bd04c0cfbfdb596 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Mon, 22 Apr 2024 21:40:17 +0000 Subject: [PATCH 08/21] Update generated code for v978 --- OPENAPI_VERSION | 2 +- stripe/_account_session.py | 21 +++++++++++++++++++++ stripe/_account_session_service.py | 21 +++++++++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index e0fe92557..381403349 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v977 \ No newline at end of file +v978 \ No newline at end of file diff --git a/stripe/_account_session.py b/stripe/_account_session.py index cc32ac5ab..330e675b4 100644 --- a/stripe/_account_session.py +++ b/stripe/_account_session.py @@ -297,6 +297,12 @@ class CreateParamsComponents(TypedDict): """ Configuration for the payment details embedded component. """ + payment_method_settings: NotRequired[ + "AccountSession.CreateParamsComponentsPaymentMethodSettings" + ] + """ + Configuration for the payment method settings embedded component. + """ payments: NotRequired["AccountSession.CreateParamsComponentsPayments"] """ Configuration for the payments embedded component. @@ -552,6 +558,21 @@ class CreateParamsComponentsPaymentDetailsFeatures(TypedDict): Whether to allow sending refunds. This is `true` by default. """ + class CreateParamsComponentsPaymentMethodSettings(TypedDict): + enabled: bool + """ + Whether the embedded component is enabled. + """ + features: NotRequired[ + "AccountSession.CreateParamsComponentsPaymentMethodSettingsFeatures" + ] + """ + The list of features enabled in the embedded component. + """ + + class CreateParamsComponentsPaymentMethodSettingsFeatures(TypedDict): + pass + class CreateParamsComponentsPayments(TypedDict): enabled: bool """ diff --git a/stripe/_account_session_service.py b/stripe/_account_session_service.py index 419564462..e53754dbe 100644 --- a/stripe/_account_session_service.py +++ b/stripe/_account_session_service.py @@ -92,6 +92,12 @@ class CreateParamsComponents(TypedDict): """ Configuration for the payment details embedded component. """ + payment_method_settings: NotRequired[ + "AccountSessionService.CreateParamsComponentsPaymentMethodSettings" + ] + """ + Configuration for the payment method settings embedded component. + """ payments: NotRequired[ "AccountSessionService.CreateParamsComponentsPayments" ] @@ -351,6 +357,21 @@ class CreateParamsComponentsPaymentDetailsFeatures(TypedDict): Whether to allow sending refunds. This is `true` by default. """ + class CreateParamsComponentsPaymentMethodSettings(TypedDict): + enabled: bool + """ + Whether the embedded component is enabled. + """ + features: NotRequired[ + "AccountSessionService.CreateParamsComponentsPaymentMethodSettingsFeatures" + ] + """ + The list of features enabled in the embedded component. + """ + + class CreateParamsComponentsPaymentMethodSettingsFeatures(TypedDict): + pass + class CreateParamsComponentsPayments(TypedDict): enabled: bool """ From c134c3cfe650ece09846d2a9f52e21c5eb4061ce Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Mon, 22 Apr 2024 22:19:40 +0000 Subject: [PATCH 09/21] Update generated code for v979 --- OPENAPI_VERSION | 2 +- stripe/_account.py | 153 ++++++++++++-------- stripe/_account_external_account_service.py | 18 ++- stripe/_account_login_link_service.py | 8 +- stripe/_account_service.py | 90 ++++++++---- stripe/_balance.py | 2 +- stripe/_bank_account.py | 7 +- stripe/_card.py | 6 +- stripe/_login_link.py | 2 +- stripe/_person.py | 5 +- stripe/_token.py | 13 +- stripe/_token_service.py | 4 +- 12 files changed, 192 insertions(+), 118 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 381403349..ee1839570 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v978 \ No newline at end of file +v979 \ No newline at end of file diff --git a/stripe/_account.py b/stripe/_account.py index d831b8e32..370a9f5c1 100644 --- a/stripe/_account.py +++ b/stripe/_account.py @@ -45,9 +45,14 @@ class Account( properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts. - For Custom accounts, the properties below are always returned. For other accounts, some properties are returned until that - account has started to go through Connect Onboarding. Once you create an [Account Link](https://stripe.com/docs/api/account_links) or [Account Session](https://stripe.com/docs/api/account_sessions), - some properties are only returned for Custom accounts. Learn about the differences [between accounts](https://stripe.com/docs/connect/accounts). + For accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) + is `application`, which includes Custom accounts, the properties below are always + returned. + + For accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) + is `stripe`, which includes Standard and Express accounts, some properties are only returned + until you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions) + to start Connect Onboarding. Learn about the [differences between accounts](https://stripe.com/connect/accounts). """ OBJECT_NAME: ClassVar[Literal["account"]] = "account" @@ -1077,7 +1082,7 @@ class Schedule(StripeObject): debit_negative_balances: bool """ - A Boolean indicating if Stripe should try to reclaim negative balances from an attached bank account. See our [Understanding Connect Account Balances](https://stripe.com/docs/connect/account-balances) documentation for details. Default value is `false` for Custom accounts, otherwise `true`. + A Boolean indicating if Stripe should try to reclaim negative balances from an attached bank account. See [Understanding Connect account balances](https://stripe.com/connect/account-balances) for details. The default value is `false` when [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts, otherwise `true`. """ schedule: Schedule statement_descriptor: Optional[str] @@ -1252,15 +1257,22 @@ class CreateParams(RequestOptions): Literal["company", "government_entity", "individual", "non_profit"] ] """ - The business type. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + The business type. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ capabilities: NotRequired["Account.CreateParamsCapabilities"] """ - Each key of the dictionary represents a capability, and each capability maps to its settings (e.g. whether it has been requested or not). Each capability will be inactive until you have provided its specific requirements and Stripe has verified them. An account may have some of its requested capabilities be active and some be inactive. + Each key of the dictionary represents a capability, and each capability + maps to its settings (for example, whether it has been requested or not). Each + capability is inactive until you have provided its specific + requirements and Stripe has verified them. An account might have some + of its requested capabilities be active and some be inactive. + + Required when [account.controller.stripe_dashboard.type](https://stripe.com/api/accounts/create#create_account-controller-dashboard-type) + is `none`, which includes Custom accounts. """ company: NotRequired["Account.CreateParamsCompany"] """ - Information about the company or business. This field is available for any `business_type`. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + Information about the company or business. This field is available for any `business_type`. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ controller: NotRequired["Account.CreateParamsController"] """ @@ -1280,7 +1292,7 @@ class CreateParams(RequestOptions): """ email: NotRequired[str] """ - The email address of the account holder. This is only to make the account easier to identify to you. Stripe only emails Custom accounts with your consent. + The email address of the account holder. This is only to make the account easier to identify to you. If [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts, Stripe doesn't email the account without your consent. """ expand: NotRequired[List[str]] """ @@ -1290,13 +1302,13 @@ class CreateParams(RequestOptions): "str|Account.CreateParamsBankAccount|Account.CreateParamsCard|Account.CreateParamsCardToken" ] """ - A card or bank account to attach to the account for receiving [payouts](https://docs.stripe.com/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://docs.stripe.com/js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://docs.stripe.com/api#account_create_bank_account) creation. + A card or bank account to attach to the account for receiving [payouts](https://stripe.com/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://stripe.com/js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://stripe.com/api#account_create_bank_account) creation. - By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the [bank account](https://docs.stripe.com/api#account_create_bank_account) or [card creation](https://docs.stripe.com/api#account_create_card) APIs. After you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the [bank account](https://stripe.com/api#account_create_bank_account) or [card creation](https://stripe.com/api#account_create_card) APIs. After you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ individual: NotRequired["Account.CreateParamsIndividual"] """ - Information about the person represented by the account. This field is null unless `business_type` is set to `individual`. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + Information about the person represented by the account. This field is null unless `business_type` is set to `individual`. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ metadata: NotRequired["Literal['']|Dict[str, str]"] """ @@ -1312,7 +1324,7 @@ class CreateParams(RequestOptions): """ tos_acceptance: NotRequired["Account.CreateParamsTosAcceptance"] """ - Details on the account's acceptance of the [Stripe Services Agreement](https://docs.stripe.com/connect/updating-accounts#tos-acceptance) This property can only be updated for Custom accounts. + Details on the account's acceptance of the [Stripe Services Agreement](https://stripe.com/connect/updating-accounts#tos-acceptance). This property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ type: NotRequired[Literal["custom", "express", "standard"]] """ @@ -3880,7 +3892,7 @@ class RetrievePersonParams(RequestOptions): Literal["company", "government_entity", "individual", "non_profit"] ] """ - The business type. Once you create an [Account Link](https://stripe.com/docs/api/account_links) or [Account Session](https://stripe.com/docs/api/account_sessions), this property is only returned for Custom accounts. + The business type. After you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property is only returned for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ capabilities: Optional[Capabilities] charges_enabled: Optional[bool] @@ -3903,7 +3915,7 @@ class RetrievePersonParams(RequestOptions): """ details_submitted: Optional[bool] """ - Whether account details have been submitted. Standard accounts cannot receive payouts before this is true. + Whether account details have been submitted. Accounts with Stripe Dashboard access, which includes Standard accounts, cannot receive payouts before this is true. """ email: Optional[str] """ @@ -3922,10 +3934,9 @@ class RetrievePersonParams(RequestOptions): """ This is an object representing a person associated with a Stripe account. - A platform cannot access a Standard or Express account's persons after the account starts onboarding, such as after generating an account link for the account. - See the [Standard onboarding](https://stripe.com/docs/connect/standard-accounts) or [Express onboarding documentation](https://stripe.com/docs/connect/express-accounts) for information about platform prefilling and account onboarding steps. + A platform cannot access a person for an account where [account.controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `stripe`, which includes Standard and Express accounts, after creating an Account Link or Account Session to start Connect onboarding. - Related guide: [Handling identity verification with the API](https://stripe.com/docs/connect/handling-api-verification#person-information) + See the [Standard onboarding](https://stripe.com/connect/standard-accounts) or [Express onboarding](https://stripe.com/connect/express-accounts) documentation for information about prefilling information and account onboarding steps. Learn more about [handling identity verification with the API](https://stripe.com/connect/handling-api-verification#person-information). """ metadata: Optional[Dict[str, str]] """ @@ -3948,7 +3959,7 @@ class RetrievePersonParams(RequestOptions): tos_acceptance: Optional[TosAcceptance] type: Optional[Literal["custom", "express", "none", "standard"]] """ - The Stripe account type. Can be `standard`, `express`, or `custom`. + The Stripe account type. Can be `standard`, `express`, `custom`, or `none`. """ deleted: Optional[Literal[True]] """ @@ -4000,9 +4011,11 @@ def _cls_delete( cls, sid: str, **params: Unpack["Account.DeleteParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. + + Test-mode accounts can be deleted at any time. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -4022,9 +4035,11 @@ def delete( sid: str, **params: Unpack["Account.DeleteParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. + + Test-mode accounts can be deleted at any time. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -4033,9 +4048,11 @@ def delete( @overload def delete(self, **params: Unpack["Account.DeleteParams"]) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Test-mode accounts can be deleted at any time. + + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -4046,9 +4063,11 @@ def delete( # pyright: ignore[reportGeneralTypeIssues] self, **params: Unpack["Account.DeleteParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. + + Test-mode accounts can be deleted at any time. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -4063,9 +4082,11 @@ async def _cls_delete_async( cls, sid: str, **params: Unpack["Account.DeleteParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. + + Test-mode accounts can be deleted at any time. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -4085,9 +4106,11 @@ async def delete_async( sid: str, **params: Unpack["Account.DeleteParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Test-mode accounts can be deleted at any time. + + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -4098,9 +4121,11 @@ async def delete_async( self, **params: Unpack["Account.DeleteParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. + + Test-mode accounts can be deleted at any time. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -4111,9 +4136,11 @@ async def delete_async( # pyright: ignore[reportGeneralTypeIssues] self, **params: Unpack["Account.DeleteParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. + + Test-mode accounts can be deleted at any time. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -4280,9 +4307,9 @@ def _cls_reject( cls, account: str, **params: Unpack["Account.RejectParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ return cast( "Account", @@ -4301,18 +4328,18 @@ def reject( account: str, **params: Unpack["Account.RejectParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ ... @overload def reject(self, **params: Unpack["Account.RejectParams"]) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ ... @@ -4321,9 +4348,9 @@ def reject( # pyright: ignore[reportGeneralTypeIssues] self, **params: Unpack["Account.RejectParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ return cast( "Account", @@ -4341,9 +4368,9 @@ async def _cls_reject_async( cls, account: str, **params: Unpack["Account.RejectParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ return cast( "Account", @@ -4362,9 +4389,9 @@ async def reject_async( account: str, **params: Unpack["Account.RejectParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ ... @@ -4373,9 +4400,9 @@ async def reject_async( self, **params: Unpack["Account.RejectParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ ... @@ -4384,9 +4411,9 @@ async def reject_async( # pyright: ignore[reportGeneralTypeIssues] self, **params: Unpack["Account.RejectParams"] ) -> "Account": """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ return cast( "Account", @@ -4663,9 +4690,14 @@ def modify_external_account( **params: Unpack["Account.ModifyExternalAccountParams"] ) -> Union["BankAccount", "Card"]: """ - Updates the metadata, account holder name, account holder type of a bank account belonging to a [Custom account](https://stripe.com/docs/connect/custom-accounts), and optionally sets it as the default for its currency. Other bank account details are not editable by design. + Updates the metadata, account holder name, account holder type of a bank account belonging to + a connected account and optionally sets it as the default for its currency. Other bank account + details are not editable by design. - You can re-enable a disabled bank account by performing an update call without providing any arguments or changes. + You can only update bank accounts when [account.controller.requirement_collection is application, which includes Custom accounts](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection). + + You can re-enable a disabled bank account by performing an update call without providing any + arguments or changes. """ return cast( Union["BankAccount", "Card"], @@ -4686,9 +4718,14 @@ async def modify_external_account_async( **params: Unpack["Account.ModifyExternalAccountParams"] ) -> Union["BankAccount", "Card"]: """ - Updates the metadata, account holder name, account holder type of a bank account belonging to a [Custom account](https://stripe.com/docs/connect/custom-accounts), and optionally sets it as the default for its currency. Other bank account details are not editable by design. + Updates the metadata, account holder name, account holder type of a bank account belonging to + a connected account and optionally sets it as the default for its currency. Other bank account + details are not editable by design. + + You can only update bank accounts when [account.controller.requirement_collection is application, which includes Custom accounts](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection). - You can re-enable a disabled bank account by performing an update call without providing any arguments or changes. + You can re-enable a disabled bank account by performing an update call without providing any + arguments or changes. """ return cast( Union["BankAccount", "Card"], @@ -4788,9 +4825,9 @@ def create_login_link( cls, account: str, **params: Unpack["Account.CreateLoginLinkParams"] ) -> "LoginLink": """ - Creates a single-use login link for an Express account to access their Stripe dashboard. + Creates a single-use login link for a connected account to access the Express Dashboard. - You may only create login links for [Express accounts](https://stripe.com/docs/connect/express-accounts) connected to your platform. + You can only create login links for accounts that use the [Express Dashboard](https://stripe.com/connect/express-dashboard) and are connected to your platform. """ return cast( "LoginLink", @@ -4808,9 +4845,9 @@ async def create_login_link_async( cls, account: str, **params: Unpack["Account.CreateLoginLinkParams"] ) -> "LoginLink": """ - Creates a single-use login link for an Express account to access their Stripe dashboard. + Creates a single-use login link for a connected account to access the Express Dashboard. - You may only create login links for [Express accounts](https://stripe.com/docs/connect/express-accounts) connected to your platform. + You can only create login links for accounts that use the [Express Dashboard](https://stripe.com/connect/express-dashboard) and are connected to your platform. """ return cast( "LoginLink", diff --git a/stripe/_account_external_account_service.py b/stripe/_account_external_account_service.py index 139a4dab0..06a2b7e77 100644 --- a/stripe/_account_external_account_service.py +++ b/stripe/_account_external_account_service.py @@ -310,9 +310,14 @@ def update( options: RequestOptions = {}, ) -> Union[BankAccount, Card]: """ - Updates the metadata, account holder name, account holder type of a bank account belonging to a [Custom account](https://stripe.com/docs/connect/custom-accounts), and optionally sets it as the default for its currency. Other bank account details are not editable by design. + Updates the metadata, account holder name, account holder type of a bank account belonging to + a connected account and optionally sets it as the default for its currency. Other bank account + details are not editable by design. - You can re-enable a disabled bank account by performing an update call without providing any arguments or changes. + You can only update bank accounts when [account.controller.requirement_collection is application, which includes Custom accounts](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection). + + You can re-enable a disabled bank account by performing an update call without providing any + arguments or changes. """ return cast( Union[BankAccount, Card], @@ -337,9 +342,14 @@ async def update_async( options: RequestOptions = {}, ) -> Union[BankAccount, Card]: """ - Updates the metadata, account holder name, account holder type of a bank account belonging to a [Custom account](https://stripe.com/docs/connect/custom-accounts), and optionally sets it as the default for its currency. Other bank account details are not editable by design. + Updates the metadata, account holder name, account holder type of a bank account belonging to + a connected account and optionally sets it as the default for its currency. Other bank account + details are not editable by design. + + You can only update bank accounts when [account.controller.requirement_collection is application, which includes Custom accounts](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection). - You can re-enable a disabled bank account by performing an update call without providing any arguments or changes. + You can re-enable a disabled bank account by performing an update call without providing any + arguments or changes. """ return cast( Union[BankAccount, Card], diff --git a/stripe/_account_login_link_service.py b/stripe/_account_login_link_service.py index 21a66ca38..d46d42165 100644 --- a/stripe/_account_login_link_service.py +++ b/stripe/_account_login_link_service.py @@ -22,9 +22,9 @@ def create( options: RequestOptions = {}, ) -> LoginLink: """ - Creates a single-use login link for an Express account to access their Stripe dashboard. + Creates a single-use login link for a connected account to access the Express Dashboard. - You may only create login links for [Express accounts](https://stripe.com/docs/connect/express-accounts) connected to your platform. + You can only create login links for accounts that use the [Express Dashboard](https://stripe.com/connect/express-dashboard) and are connected to your platform. """ return cast( LoginLink, @@ -47,9 +47,9 @@ async def create_async( options: RequestOptions = {}, ) -> LoginLink: """ - Creates a single-use login link for an Express account to access their Stripe dashboard. + Creates a single-use login link for a connected account to access the Express Dashboard. - You may only create login links for [Express accounts](https://stripe.com/docs/connect/express-accounts) connected to your platform. + You can only create login links for accounts that use the [Express Dashboard](https://stripe.com/connect/express-dashboard) and are connected to your platform. """ return cast( LoginLink, diff --git a/stripe/_account_service.py b/stripe/_account_service.py index 1e1416693..67e69811a 100644 --- a/stripe/_account_service.py +++ b/stripe/_account_service.py @@ -38,15 +38,22 @@ class CreateParams(TypedDict): Literal["company", "government_entity", "individual", "non_profit"] ] """ - The business type. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + The business type. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ capabilities: NotRequired["AccountService.CreateParamsCapabilities"] """ - Each key of the dictionary represents a capability, and each capability maps to its settings (e.g. whether it has been requested or not). Each capability will be inactive until you have provided its specific requirements and Stripe has verified them. An account may have some of its requested capabilities be active and some be inactive. + Each key of the dictionary represents a capability, and each capability + maps to its settings (for example, whether it has been requested or not). Each + capability is inactive until you have provided its specific + requirements and Stripe has verified them. An account might have some + of its requested capabilities be active and some be inactive. + + Required when [account.controller.stripe_dashboard.type](https://stripe.com/api/accounts/create#create_account-controller-dashboard-type) + is `none`, which includes Custom accounts. """ company: NotRequired["AccountService.CreateParamsCompany"] """ - Information about the company or business. This field is available for any `business_type`. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + Information about the company or business. This field is available for any `business_type`. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ controller: NotRequired["AccountService.CreateParamsController"] """ @@ -66,7 +73,7 @@ class CreateParams(TypedDict): """ email: NotRequired[str] """ - The email address of the account holder. This is only to make the account easier to identify to you. Stripe only emails Custom accounts with your consent. + The email address of the account holder. This is only to make the account easier to identify to you. If [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts, Stripe doesn't email the account without your consent. """ expand: NotRequired[List[str]] """ @@ -76,13 +83,13 @@ class CreateParams(TypedDict): "str|AccountService.CreateParamsBankAccount|AccountService.CreateParamsCard|AccountService.CreateParamsCardToken" ] """ - A card or bank account to attach to the account for receiving [payouts](https://docs.stripe.com/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://docs.stripe.com/js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://docs.stripe.com/api#account_create_bank_account) creation. + A card or bank account to attach to the account for receiving [payouts](https://stripe.com/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://stripe.com/js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://stripe.com/api#account_create_bank_account) creation. - By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the [bank account](https://docs.stripe.com/api#account_create_bank_account) or [card creation](https://docs.stripe.com/api#account_create_card) APIs. After you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the [bank account](https://stripe.com/api#account_create_bank_account) or [card creation](https://stripe.com/api#account_create_card) APIs. After you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ individual: NotRequired["AccountService.CreateParamsIndividual"] """ - Information about the person represented by the account. This field is null unless `business_type` is set to `individual`. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + Information about the person represented by the account. This field is null unless `business_type` is set to `individual`. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ metadata: NotRequired["Literal['']|Dict[str, str]"] """ @@ -98,7 +105,7 @@ class CreateParams(TypedDict): """ tos_acceptance: NotRequired["AccountService.CreateParamsTosAcceptance"] """ - Details on the account's acceptance of the [Stripe Services Agreement](https://docs.stripe.com/connect/updating-accounts#tos-acceptance) This property can only be updated for Custom accounts. + Details on the account's acceptance of the [Stripe Services Agreement](https://stripe.com/connect/updating-accounts#tos-acceptance). This property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ type: NotRequired[Literal["custom", "express", "standard"]] """ @@ -1751,15 +1758,22 @@ class UpdateParams(TypedDict): Literal["company", "government_entity", "individual", "non_profit"] ] """ - The business type. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + The business type. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ capabilities: NotRequired["AccountService.UpdateParamsCapabilities"] """ - Each key of the dictionary represents a capability, and each capability maps to its settings (e.g. whether it has been requested or not). Each capability will be inactive until you have provided its specific requirements and Stripe has verified them. An account may have some of its requested capabilities be active and some be inactive. + Each key of the dictionary represents a capability, and each capability + maps to its settings (for example, whether it has been requested or not). Each + capability is inactive until you have provided its specific + requirements and Stripe has verified them. An account might have some + of its requested capabilities be active and some be inactive. + + Required when [account.controller.stripe_dashboard.type](https://stripe.com/api/accounts/create#create_account-controller-dashboard-type) + is `none`, which includes Custom accounts. """ company: NotRequired["AccountService.UpdateParamsCompany"] """ - Information about the company or business. This field is available for any `business_type`. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + Information about the company or business. This field is available for any `business_type`. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ default_currency: NotRequired[str] """ @@ -1771,7 +1785,7 @@ class UpdateParams(TypedDict): """ email: NotRequired[str] """ - The email address of the account holder. This is only to make the account easier to identify to you. Stripe only emails Custom accounts with your consent. + The email address of the account holder. This is only to make the account easier to identify to you. If [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts, Stripe doesn't email the account without your consent. """ expand: NotRequired[List[str]] """ @@ -1781,13 +1795,13 @@ class UpdateParams(TypedDict): "Literal['']|str|AccountService.UpdateParamsBankAccount|AccountService.UpdateParamsCard|AccountService.UpdateParamsCardToken" ] """ - A card or bank account to attach to the account for receiving [payouts](https://docs.stripe.com/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://docs.stripe.com/js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://docs.stripe.com/api#account_create_bank_account) creation. + A card or bank account to attach to the account for receiving [payouts](https://stripe.com/connect/bank-debit-card-payouts) (you won't be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](https://stripe.com/js), or a dictionary, as documented in the `external_account` parameter for [bank account](https://stripe.com/api#account_create_bank_account) creation. - By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the [bank account](https://docs.stripe.com/api#account_create_bank_account) or [card creation](https://docs.stripe.com/api#account_create_card) APIs. After you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the [bank account](https://stripe.com/api#account_create_bank_account) or [card creation](https://stripe.com/api#account_create_card) APIs. After you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ individual: NotRequired["AccountService.UpdateParamsIndividual"] """ - Information about the person represented by the account. This field is null unless `business_type` is set to `individual`. Once you create an [Account Link](https://docs.stripe.com/api/account_links) or [Account Session](https://docs.stripe.com/api/account_sessions), this property can only be updated for Custom accounts. + Information about the person represented by the account. This field is null unless `business_type` is set to `individual`. Once you create an [Account Link](https://stripe.com/api/account_links) or [Account Session](https://stripe.com/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ metadata: NotRequired["Literal['']|Dict[str, str]"] """ @@ -1803,7 +1817,7 @@ class UpdateParams(TypedDict): """ tos_acceptance: NotRequired["AccountService.UpdateParamsTosAcceptance"] """ - Details on the account's acceptance of the [Stripe Services Agreement](https://docs.stripe.com/connect/updating-accounts#tos-acceptance) This property can only be updated for Custom accounts. + Details on the account's acceptance of the [Stripe Services Agreement](https://stripe.com/connect/updating-accounts#tos-acceptance). This property can only be updated for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ class UpdateParamsBankAccount(TypedDict): @@ -3319,9 +3333,11 @@ def delete( options: RequestOptions = {}, ) -> Account: """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. + + Test-mode accounts can be deleted at any time. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -3344,9 +3360,11 @@ async def delete_async( options: RequestOptions = {}, ) -> Account: """ - With [Connect](https://stripe.com/docs/connect), you can delete accounts you manage. + With [Connect](https://stripe.com/connect), you can delete accounts you manage. - Accounts created using test-mode keys can be deleted at any time. Standard accounts created using live-mode keys cannot be deleted. Custom or Express accounts created using live-mode keys can only be deleted once all balances are zero. + Test-mode accounts can be deleted at any time. + + Live-mode accounts where Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. Live-mode accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be deleted when all [balances](https://stripe.com/api/balance/balanace_object) are zero. If you want to delete your own account, use the [account information tab in your account settings](https://dashboard.stripe.com/settings/account) instead. """ @@ -3411,12 +3429,16 @@ def update( options: RequestOptions = {}, ) -> Account: """ - Updates a [connected account](https://stripe.com/docs/connect/accounts) by setting the values of the parameters passed. Any parameters not provided are + Updates a [connected account](https://stripe.com/connect/accounts) by setting the values of the parameters passed. Any parameters not provided are left unchanged. - For Custom accounts, you can update any information on the account. For other accounts, you can update all information until that - account has started to go through Connect Onboarding. Once you create an [Account Link or Account Session](https://stripe.com/docs/api/account_links), - some properties can only be changed or updated for Custom accounts. + For accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) + is application, which includes Custom accounts, you can update any information on the account. + + For accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) + is stripe, which includes Standard and Express accounts, you can update all information until you create + an [Account Link or Account Session](https://stripe.com/api/account_links) to start Connect onboarding, + after which some properties can no longer be updated. To update your own account, use the [Dashboard](https://dashboard.stripe.com/settings/account). Refer to our [Connect](https://stripe.com/docs/connect/updating-accounts) documentation to learn more about updating accounts. @@ -3440,12 +3462,16 @@ async def update_async( options: RequestOptions = {}, ) -> Account: """ - Updates a [connected account](https://stripe.com/docs/connect/accounts) by setting the values of the parameters passed. Any parameters not provided are + Updates a [connected account](https://stripe.com/connect/accounts) by setting the values of the parameters passed. Any parameters not provided are left unchanged. - For Custom accounts, you can update any information on the account. For other accounts, you can update all information until that - account has started to go through Connect Onboarding. Once you create an [Account Link or Account Session](https://stripe.com/docs/api/account_links), - some properties can only be changed or updated for Custom accounts. + For accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) + is application, which includes Custom accounts, you can update any information on the account. + + For accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) + is stripe, which includes Standard and Express accounts, you can update all information until you create + an [Account Link or Account Session](https://stripe.com/api/account_links) to start Connect onboarding, + after which some properties can no longer be updated. To update your own account, use the [Dashboard](https://dashboard.stripe.com/settings/account). Refer to our [Connect](https://stripe.com/docs/connect/updating-accounts) documentation to learn more about updating accounts. @@ -3599,9 +3625,9 @@ def reject( options: RequestOptions = {}, ) -> Account: """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ return cast( Account, @@ -3624,9 +3650,9 @@ async def reject_async( options: RequestOptions = {}, ) -> Account: """ - With [Connect](https://stripe.com/docs/connect), you may flag accounts as suspicious. + With [Connect](https://stripe.com/connect), you can reject accounts that you have flagged as suspicious. - Test-mode Custom and Express accounts can be rejected at any time. Accounts created using live-mode keys may only be rejected once all balances are zero. + Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected. Test-mode accounts can be rejected at any time. Live-mode accounts can only be rejected after all balances are zero. """ return cast( Account, diff --git a/stripe/_balance.py b/stripe/_balance.py index 50b24f8e2..1cbc6312e 100644 --- a/stripe/_balance.py +++ b/stripe/_balance.py @@ -173,7 +173,7 @@ class RetrieveParams(RequestOptions): """ connect_reserved: Optional[List[ConnectReserved]] """ - Funds held due to negative balances on connected Custom accounts. You can find the connect reserve balance for each currency and payment type in the `source_types` property. + Funds held due to negative balances on connected accounts where [account.controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. You can find the connect reserve balance for each currency and payment type in the `source_types` property. """ instant_available: Optional[List[InstantAvailable]] """ diff --git a/stripe/_bank_account.py b/stripe/_bank_account.py index 39e2d806d..c74515d33 100644 --- a/stripe/_bank_account.py +++ b/stripe/_bank_account.py @@ -25,11 +25,12 @@ class BankAccount( """ These bank accounts are payment methods on `Customer` objects. - On the other hand [External Accounts](https://stripe.com/docs/api#external_accounts) are transfer - destinations on `Account` objects for [Custom accounts](https://stripe.com/docs/connect/custom-accounts). + On the other hand [External Accounts](https://stripe.com/api#external_accounts) are transfer + destinations on `Account` objects for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) + is `application`, which includes [Custom accounts](https://stripe.com/connect/custom-accounts). They can be bank accounts or debit cards as well, and are documented in the links above. - Related guide: [Bank debits and transfers](https://stripe.com/docs/payments/bank-debits-transfers) + Related guide: [Bank debits and transfers](https://stripe.com/payments/bank-debits-transfers) """ OBJECT_NAME: ClassVar[Literal["bank_account"]] = "bank_account" diff --git a/stripe/_card.py b/stripe/_card.py index a83c74af9..434bad80a 100644 --- a/stripe/_card.py +++ b/stripe/_card.py @@ -38,7 +38,7 @@ class DeleteParams(RequestOptions): account: Optional[ExpandableField["Account"]] """ - The account this card belongs to. This attribute will not be in the card object if the card belongs to a customer or recipient instead. + The account this card belongs to. This attribute will not be in the card object if the card belongs to a customer or recipient instead. This property is only available for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ address_city: Optional[str] """ @@ -86,7 +86,7 @@ class DeleteParams(RequestOptions): """ currency: Optional[str] """ - Three-letter [ISO code for currency](https://stripe.com/docs/payouts). Only applicable on accounts (not customers or recipients). The card can be used as a transfer destination for funds in this currency. + Three-letter [ISO code for currency](https://stripe.com/docs/payouts). Only applicable on accounts (not customers or recipients). The card can be used as a transfer destination for funds in this currency. This property is only available for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ customer: Optional[ExpandableField["Customer"]] """ @@ -98,7 +98,7 @@ class DeleteParams(RequestOptions): """ default_for_currency: Optional[bool] """ - Whether this card is the default external account for its currency. + Whether this card is the default external account for its currency. This property is only available for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. """ description: Optional[str] """ diff --git a/stripe/_login_link.py b/stripe/_login_link.py index dae7a85e6..0b6cdd24a 100644 --- a/stripe/_login_link.py +++ b/stripe/_login_link.py @@ -7,7 +7,7 @@ class LoginLink(StripeObject): """ - Login Links are single-use login link for an Express account to access their Stripe dashboard. + Login Links are single-use URLs for a connected account to access the Express Dashboard. The connected account's [account.controller.stripe_dashboard.type](https://stripe.com/api/accounts/object#account_object-controller-stripe_dashboard-type) must be `express` to have access to the Express Dashboard. """ OBJECT_NAME: ClassVar[Literal["login_link"]] = "login_link" diff --git a/stripe/_person.py b/stripe/_person.py index 666320784..d3461e966 100644 --- a/stripe/_person.py +++ b/stripe/_person.py @@ -16,10 +16,9 @@ class Person(UpdateableAPIResource["Person"]): """ This is an object representing a person associated with a Stripe account. - A platform cannot access a Standard or Express account's persons after the account starts onboarding, such as after generating an account link for the account. - See the [Standard onboarding](https://stripe.com/docs/connect/standard-accounts) or [Express onboarding documentation](https://stripe.com/docs/connect/express-accounts) for information about platform prefilling and account onboarding steps. + A platform cannot access a person for an account where [account.controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is `stripe`, which includes Standard and Express accounts, after creating an Account Link or Account Session to start Connect onboarding. - Related guide: [Handling identity verification with the API](https://stripe.com/docs/connect/handling-api-verification#person-information) + See the [Standard onboarding](https://stripe.com/connect/standard-accounts) or [Express onboarding](https://stripe.com/connect/express-accounts) documentation for information about prefilling information and account onboarding steps. Learn more about [handling identity verification with the API](https://stripe.com/connect/handling-api-verification#person-information). """ OBJECT_NAME: ClassVar[Literal["person"]] = "person" diff --git a/stripe/_token.py b/stripe/_token.py index 030021238..8da78239c 100644 --- a/stripe/_token.py +++ b/stripe/_token.py @@ -35,7 +35,7 @@ class Token(CreateableAPIResource["Token"]): You can't store or use tokens more than once. To store card or bank account information for later use, create [Customer](https://stripe.com/docs/api#customers) - objects or [Custom accounts](https://stripe.com/docs/api#external_accounts). + objects or [External accounts](https://stripe.com/api#external_accounts). [Radar](https://stripe.com/docs/radar), our integrated solution for automatic fraud protection, performs best with integrations that use client-side tokenization. """ @@ -1068,11 +1068,12 @@ class RetrieveParams(RequestOptions): """ These bank accounts are payment methods on `Customer` objects. - On the other hand [External Accounts](https://stripe.com/docs/api#external_accounts) are transfer - destinations on `Account` objects for [Custom accounts](https://stripe.com/docs/connect/custom-accounts). + On the other hand [External Accounts](https://stripe.com/api#external_accounts) are transfer + destinations on `Account` objects for accounts where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) + is `application`, which includes [Custom accounts](https://stripe.com/connect/custom-accounts). They can be bank accounts or debit cards as well, and are documented in the links above. - Related guide: [Bank debits and transfers](https://stripe.com/docs/payments/bank-debits-transfers) + Related guide: [Bank debits and transfers](https://stripe.com/payments/bank-debits-transfers) """ card: Optional["Card"] """ @@ -1115,7 +1116,7 @@ class RetrieveParams(RequestOptions): def create(cls, **params: Unpack["Token.CreateParams"]) -> "Token": """ Creates a single-use token that represents a bank account's details. - You can use this token with any API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a [Custom account](https://stripe.com/docs/api#accounts). + You can use this token with any API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a [connected account](https://stripe.com/docs/api#accounts) where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is application, which includes Custom accounts. """ return cast( "Token", @@ -1132,7 +1133,7 @@ async def create_async( ) -> "Token": """ Creates a single-use token that represents a bank account's details. - You can use this token with any API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a [Custom account](https://stripe.com/docs/api#accounts). + You can use this token with any API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a [connected account](https://stripe.com/docs/api#accounts) where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is application, which includes Custom accounts. """ return cast( "Token", diff --git a/stripe/_token_service.py b/stripe/_token_service.py index 2348e62af..445eeb773 100644 --- a/stripe/_token_service.py +++ b/stripe/_token_service.py @@ -1094,7 +1094,7 @@ def create( ) -> Token: """ Creates a single-use token that represents a bank account's details. - You can use this token with any API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a [Custom account](https://stripe.com/docs/api#accounts). + You can use this token with any API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a [connected account](https://stripe.com/docs/api#accounts) where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is application, which includes Custom accounts. """ return cast( Token, @@ -1115,7 +1115,7 @@ async def create_async( ) -> Token: """ Creates a single-use token that represents a bank account's details. - You can use this token with any API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a [Custom account](https://stripe.com/docs/api#accounts). + You can use this token with any API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a [connected account](https://stripe.com/docs/api#accounts) where [controller.requirement_collection](https://stripe.com/api/accounts/object#account_object-controller-requirement_collection) is application, which includes Custom accounts. """ return cast( Token, From da5662265facb31f6cc171db9d69315d4c27c20c Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Mon, 22 Apr 2024 23:24:47 +0000 Subject: [PATCH 10/21] Update generated code for v980 --- OPENAPI_VERSION | 2 +- stripe/_quote.py | 40 ++++++++++++++++++++++++++++++++++++++++ stripe/_quote_line.py | 19 +++++++++++++++++++ stripe/_quote_service.py | 40 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 100 insertions(+), 1 deletion(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index ee1839570..212870537 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v979 \ No newline at end of file +v980 \ No newline at end of file diff --git a/stripe/_quote.py b/stripe/_quote.py index 396e14cf1..b13b8dacc 100644 --- a/stripe/_quote.py +++ b/stripe/_quote.py @@ -1101,6 +1101,12 @@ class CreateParamsLine(TypedDict): """ For a point-in-time operation, this attribute lets you set or update whether the subscription's billing cycle anchor is reset at the `starts_at` timestamp. """ + cancel_subscription_schedule: NotRequired[ + "Quote.CreateParamsLineCancelSubscriptionSchedule" + ] + """ + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + """ ends_at: NotRequired["Quote.CreateParamsLineEndsAt"] """ Details to identify the end of the time range modified by the proposed change. If not supplied, the quote line is considered a point-in-time operation that only affects the exact timestamp at `starts_at`, and a restricted set of attributes is supported on the quote line. @@ -1436,6 +1442,20 @@ class CreateParamsLineAppliesTo(TypedDict): Describes whether the quote line is affecting a new schedule or an existing schedule. """ + class CreateParamsLineCancelSubscriptionSchedule(TypedDict): + cancel_at: Literal["line_starts_at"] + """ + Timestamp helper to cancel the underlying schedule on the accompanying line's start date. Must be set to `line_starts_at`. + """ + invoice_now: NotRequired[bool] + """ + If the subscription schedule is `active`, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Boolean that defaults to `true`. + """ + prorate: NotRequired[bool] + """ + If the subscription schedule is `active`, indicates if the cancellation should be prorated. Boolean that defaults to `true`. + """ + class CreateParamsLineEndsAt(TypedDict): discount_end: NotRequired["Quote.CreateParamsLineEndsAtDiscountEnd"] """ @@ -2581,6 +2601,12 @@ class ModifyParamsLine(TypedDict): """ For a point-in-time operation, this attribute lets you set or update whether the subscription's billing cycle anchor is reset at the `starts_at` timestamp. """ + cancel_subscription_schedule: NotRequired[ + "Quote.ModifyParamsLineCancelSubscriptionSchedule" + ] + """ + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + """ ends_at: NotRequired["Quote.ModifyParamsLineEndsAt"] """ Details to identify the end of the time range modified by the proposed change. If not supplied, the quote line is considered a point-in-time operation that only affects the exact timestamp at `starts_at`, and a restricted set of attributes is supported on the quote line. @@ -2920,6 +2946,20 @@ class ModifyParamsLineAppliesTo(TypedDict): Describes whether the quote line is affecting a new schedule or an existing schedule. """ + class ModifyParamsLineCancelSubscriptionSchedule(TypedDict): + cancel_at: Literal["line_starts_at"] + """ + Timestamp helper to cancel the underlying schedule on the accompanying line's start date. Must be set to `line_starts_at`. + """ + invoice_now: NotRequired[bool] + """ + If the subscription schedule is `active`, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Boolean that defaults to `true`. + """ + prorate: NotRequired[bool] + """ + If the subscription schedule is `active`, indicates if the cancellation should be prorated. Boolean that defaults to `true`. + """ + class ModifyParamsLineEndsAt(TypedDict): discount_end: NotRequired["Quote.ModifyParamsLineEndsAtDiscountEnd"] """ diff --git a/stripe/_quote_line.py b/stripe/_quote_line.py index 0362e9d9b..1633c732b 100644 --- a/stripe/_quote_line.py +++ b/stripe/_quote_line.py @@ -321,6 +321,20 @@ class AppliesTo(StripeObject): Describes whether the quote line is affecting a new schedule or an existing schedule. """ + class CancelSubscriptionSchedule(StripeObject): + cancel_at: Literal["line_starts_at"] + """ + Timestamp helper to cancel the underlying schedule on the accompanying line's start date. Must be set to `line_starts_at`. + """ + invoice_now: Optional[bool] + """ + If the subscription schedule is `active`, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Boolean that defaults to `true`. + """ + prorate: Optional[bool] + """ + If the subscription schedule is `active`, indicates if the cancellation should be prorated. Boolean that defaults to `true`. + """ + class EndsAt(StripeObject): class DiscountEnd(StripeObject): discount: str @@ -459,6 +473,10 @@ class EndBehavior(StripeObject): """ For a point-in-time operation, this attribute lets you set or update whether the subscription's billing cycle anchor is reset at the `starts_at` timestamp. """ + cancel_subscription_schedule: Optional[CancelSubscriptionSchedule] + """ + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + """ ends_at: Optional[EndsAt] """ Details to identify the end of the time range modified by the proposed change. If not supplied, the quote line is considered a point-in-time operation that only affects the exact timestamp at `starts_at`, and a restricted set of attributes is supported on the quote line. @@ -496,6 +514,7 @@ class EndBehavior(StripeObject): _inner_class_types = { "actions": Action, "applies_to": AppliesTo, + "cancel_subscription_schedule": CancelSubscriptionSchedule, "ends_at": EndsAt, "set_pause_collection": SetPauseCollection, "starts_at": StartsAt, diff --git a/stripe/_quote_service.py b/stripe/_quote_service.py index aceedb654..148ae8320 100644 --- a/stripe/_quote_service.py +++ b/stripe/_quote_service.py @@ -271,6 +271,12 @@ class CreateParamsLine(TypedDict): """ For a point-in-time operation, this attribute lets you set or update whether the subscription's billing cycle anchor is reset at the `starts_at` timestamp. """ + cancel_subscription_schedule: NotRequired[ + "QuoteService.CreateParamsLineCancelSubscriptionSchedule" + ] + """ + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + """ ends_at: NotRequired["QuoteService.CreateParamsLineEndsAt"] """ Details to identify the end of the time range modified by the proposed change. If not supplied, the quote line is considered a point-in-time operation that only affects the exact timestamp at `starts_at`, and a restricted set of attributes is supported on the quote line. @@ -614,6 +620,20 @@ class CreateParamsLineAppliesTo(TypedDict): Describes whether the quote line is affecting a new schedule or an existing schedule. """ + class CreateParamsLineCancelSubscriptionSchedule(TypedDict): + cancel_at: Literal["line_starts_at"] + """ + Timestamp helper to cancel the underlying schedule on the accompanying line's start date. Must be set to `line_starts_at`. + """ + invoice_now: NotRequired[bool] + """ + If the subscription schedule is `active`, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Boolean that defaults to `true`. + """ + prorate: NotRequired[bool] + """ + If the subscription schedule is `active`, indicates if the cancellation should be prorated. Boolean that defaults to `true`. + """ + class CreateParamsLineEndsAt(TypedDict): discount_end: NotRequired[ "QuoteService.CreateParamsLineEndsAtDiscountEnd" @@ -1713,6 +1733,12 @@ class UpdateParamsLine(TypedDict): """ For a point-in-time operation, this attribute lets you set or update whether the subscription's billing cycle anchor is reset at the `starts_at` timestamp. """ + cancel_subscription_schedule: NotRequired[ + "QuoteService.UpdateParamsLineCancelSubscriptionSchedule" + ] + """ + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + """ ends_at: NotRequired["QuoteService.UpdateParamsLineEndsAt"] """ Details to identify the end of the time range modified by the proposed change. If not supplied, the quote line is considered a point-in-time operation that only affects the exact timestamp at `starts_at`, and a restricted set of attributes is supported on the quote line. @@ -2060,6 +2086,20 @@ class UpdateParamsLineAppliesTo(TypedDict): Describes whether the quote line is affecting a new schedule or an existing schedule. """ + class UpdateParamsLineCancelSubscriptionSchedule(TypedDict): + cancel_at: Literal["line_starts_at"] + """ + Timestamp helper to cancel the underlying schedule on the accompanying line's start date. Must be set to `line_starts_at`. + """ + invoice_now: NotRequired[bool] + """ + If the subscription schedule is `active`, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Boolean that defaults to `true`. + """ + prorate: NotRequired[bool] + """ + If the subscription schedule is `active`, indicates if the cancellation should be prorated. Boolean that defaults to `true`. + """ + class UpdateParamsLineEndsAt(TypedDict): discount_end: NotRequired[ "QuoteService.UpdateParamsLineEndsAtDiscountEnd" From b84acd262c8ef4ade1796988fb16ea3607fce0cf Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Tue, 23 Apr 2024 13:03:25 +0000 Subject: [PATCH 11/21] Update generated code for v981 --- OPENAPI_VERSION | 2 +- stripe/_event.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 212870537..4db457fa8 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v980 \ No newline at end of file +v981 \ No newline at end of file diff --git a/stripe/_event.py b/stripe/_event.py index 0769c1b79..8a7c3ee87 100644 --- a/stripe/_event.py +++ b/stripe/_event.py @@ -68,7 +68,7 @@ class StripeSendWebhookCustomEvent(StripeObject): trigger: str """ The trigger name of the automation that triggered this action. - Please visit [Revenue and retention automations](https://stripe.com/docs/billing/revenue-recovery/automations#choose-a-trigger) for all possible trigger names. + Please visit [Revenue and retention automations](https://stripe.com/docs/billing/automations#choose-a-trigger) for all possible trigger names. """ type: Literal["stripe_send_webhook_custom_event"] """ @@ -198,7 +198,7 @@ class RetrieveParams(RequestOptions): """ reason: Optional[Reason] """ - Information about the action that causes the event. Only present when the event is triggered by an API request or an [Automation](https://stripe.com/docs/billing/revenue-recovery/automations) action. + Information about the action that causes the event. Only present when the event is triggered by an API request or an [Automation](https://stripe.com/docs/billing/automations) action. """ request: Optional[Request] """ From 2f8d22053b91d518492c4bd05650a68491c70664 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Tue, 23 Apr 2024 17:44:42 +0000 Subject: [PATCH 12/21] Update generated code for v982 --- OPENAPI_VERSION | 2 +- stripe/entitlements/_active_entitlement.py | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 4db457fa8..735a5bbc2 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v981 \ No newline at end of file +v982 \ No newline at end of file diff --git a/stripe/entitlements/_active_entitlement.py b/stripe/entitlements/_active_entitlement.py index 82298a396..7fa4f76f8 100644 --- a/stripe/entitlements/_active_entitlement.py +++ b/stripe/entitlements/_active_entitlement.py @@ -1,10 +1,14 @@ # -*- coding: utf-8 -*- # File generated from our OpenAPI spec +from stripe._expandable_field import ExpandableField from stripe._list_object import ListObject from stripe._listable_api_resource import ListableAPIResource from stripe._request_options import RequestOptions from typing import ClassVar, List -from typing_extensions import Literal, NotRequired, Unpack +from typing_extensions import Literal, NotRequired, Unpack, TYPE_CHECKING + +if TYPE_CHECKING: + from stripe.entitlements._feature import Feature class ActiveEntitlement(ListableAPIResource["ActiveEntitlement"]): @@ -44,9 +48,9 @@ class RetrieveParams(RequestOptions): Specifies which fields in the response should be expanded. """ - feature: str + feature: ExpandableField["Feature"] """ - The feature that the customer is entitled to. + The [Feature](https://stripe.com/docs/api/entitlements/feature) that the customer is entitled to. """ id: str """ From 54a4aec290b28d0d9a9c69f524cc6b535a4c2752 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Tue, 23 Apr 2024 18:50:23 +0000 Subject: [PATCH 13/21] Update generated code for v983 --- OPENAPI_VERSION | 2 +- stripe/_product.py | 2 +- stripe/_product_feature_service.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 735a5bbc2..56fee85a7 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v982 \ No newline at end of file +v983 \ No newline at end of file diff --git a/stripe/_product.py b/stripe/_product.py index 7505e560e..4abd22822 100644 --- a/stripe/_product.py +++ b/stripe/_product.py @@ -111,7 +111,7 @@ class FixedAmount(StripeObject): class CreateFeatureParams(RequestOptions): entitlement_feature: str """ - The ID of the [Feature](docs/api/entitlements/feature) object attached to this product. + The ID of the [Feature](https://stripe.com/docs/api/entitlements/feature) object attached to this product. """ expand: NotRequired[List[str]] """ diff --git a/stripe/_product_feature_service.py b/stripe/_product_feature_service.py index 700cb234c..dfda8ed8f 100644 --- a/stripe/_product_feature_service.py +++ b/stripe/_product_feature_service.py @@ -13,7 +13,7 @@ class ProductFeatureService(StripeService): class CreateParams(TypedDict): entitlement_feature: str """ - The ID of the [Feature](docs/api/entitlements/feature) object attached to this product. + The ID of the [Feature](https://stripe.com/docs/api/entitlements/feature) object attached to this product. """ expand: NotRequired[List[str]] """ From 06f9ef232248cdea8d7ee66fc4fd187009b1301e Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Tue, 23 Apr 2024 23:15:51 +0000 Subject: [PATCH 14/21] Update generated code for v984 --- OPENAPI_VERSION | 2 +- stripe/_quote.py | 4 ++-- stripe/_quote_line.py | 2 +- stripe/_quote_service.py | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 56fee85a7..a040219e6 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v983 \ No newline at end of file +v984 \ No newline at end of file diff --git a/stripe/_quote.py b/stripe/_quote.py index b13b8dacc..3e68da05f 100644 --- a/stripe/_quote.py +++ b/stripe/_quote.py @@ -1105,7 +1105,7 @@ class CreateParamsLine(TypedDict): "Quote.CreateParamsLineCancelSubscriptionSchedule" ] """ - A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for modifications to the metadata, collection_method or invoice_settings. """ ends_at: NotRequired["Quote.CreateParamsLineEndsAt"] """ @@ -2605,7 +2605,7 @@ class ModifyParamsLine(TypedDict): "Quote.ModifyParamsLineCancelSubscriptionSchedule" ] """ - A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for modifications to the metadata, collection_method or invoice_settings. """ ends_at: NotRequired["Quote.ModifyParamsLineEndsAt"] """ diff --git a/stripe/_quote_line.py b/stripe/_quote_line.py index 1633c732b..680683a1a 100644 --- a/stripe/_quote_line.py +++ b/stripe/_quote_line.py @@ -475,7 +475,7 @@ class EndBehavior(StripeObject): """ cancel_subscription_schedule: Optional[CancelSubscriptionSchedule] """ - A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for modifications to the metadata, collection_method or invoice_settings. """ ends_at: Optional[EndsAt] """ diff --git a/stripe/_quote_service.py b/stripe/_quote_service.py index 148ae8320..069edb93e 100644 --- a/stripe/_quote_service.py +++ b/stripe/_quote_service.py @@ -275,7 +275,7 @@ class CreateParamsLine(TypedDict): "QuoteService.CreateParamsLineCancelSubscriptionSchedule" ] """ - A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for modifications to the metadata, collection_method or invoice_settings. """ ends_at: NotRequired["QuoteService.CreateParamsLineEndsAt"] """ @@ -1737,7 +1737,7 @@ class UpdateParamsLine(TypedDict): "QuoteService.UpdateParamsLineCancelSubscriptionSchedule" ] """ - A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for metadata modifications. + A point-in-time operation that cancels an existing subscription schedule at the line's starts_at timestamp. Currently only compatible with `quote_acceptance_date` for `starts_at`. When using cancel_subscription_schedule, the subscription schedule on the quote remains unalterable, except for modifications to the metadata, collection_method or invoice_settings. """ ends_at: NotRequired["QuoteService.UpdateParamsLineEndsAt"] """ From b127f1a52e41bf45e96be3e735619fa7a8a632e1 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 24 Apr 2024 13:04:59 +0000 Subject: [PATCH 15/21] Update generated code for v985 --- OPENAPI_VERSION | 2 +- stripe/_event.py | 12 ++++++------ stripe/_event_service.py | 4 ++-- stripe/_webhook_endpoint.py | 6 +++--- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index a040219e6..8a5a8933c 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v984 \ No newline at end of file +v985 \ No newline at end of file diff --git a/stripe/_event.py b/stripe/_event.py index 8a7c3ee87..8f0d6f923 100644 --- a/stripe/_event.py +++ b/stripe/_event.py @@ -31,10 +31,10 @@ class Event(ListableAPIResource["Event"]): `Event` objects directly to an endpoint on your server. You can manage webhooks in your [account settings](https://dashboard.stripe.com/account/webhooks). Learn how - to [listen for events](https://stripe.com/docs/webhooks) + to [listen for events](https://docs.stripe.com/webhooks) so that your integration can automatically trigger reactions. - When using [Connect](https://stripe.com/docs/connect), you can also receive event notifications + When using [Connect](https://docs.stripe.com/connect), you can also receive event notifications that occur in connected accounts. For these events, there's an additional `account` attribute in the received `Event` object. @@ -68,7 +68,7 @@ class StripeSendWebhookCustomEvent(StripeObject): trigger: str """ The trigger name of the automation that triggered this action. - Please visit [Revenue and retention automations](https://stripe.com/docs/billing/automations#choose-a-trigger) for all possible trigger names. + Please visit [Revenue and retention automations](https://docs.stripe.com/billing/automations#choose-a-trigger) for all possible trigger names. """ type: Literal["stripe_send_webhook_custom_event"] """ @@ -198,7 +198,7 @@ class RetrieveParams(RequestOptions): """ reason: Optional[Reason] """ - Information about the action that causes the event. Only present when the event is triggered by an API request or an [Automation](https://stripe.com/docs/billing/automations) action. + Information about the action that causes the event. Only present when the event is triggered by an API request or an [Automation](https://docs.stripe.com/billing/automations) action. """ request: Optional[Request] """ @@ -469,7 +469,7 @@ class RetrieveParams(RequestOptions): @classmethod def list(cls, **params: Unpack["Event.ListParams"]) -> ListObject["Event"]: """ - List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in [event object](https://stripe.com/docs/api/events/object) api_version attribute (not according to your current Stripe API version or Stripe-Version header). + List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in [event object](https://docs.stripe.com/api/events/object) api_version attribute (not according to your current Stripe API version or Stripe-Version header). """ result = cls._static_request( "get", @@ -490,7 +490,7 @@ async def list_async( cls, **params: Unpack["Event.ListParams"] ) -> ListObject["Event"]: """ - List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in [event object](https://stripe.com/docs/api/events/object) api_version attribute (not according to your current Stripe API version or Stripe-Version header). + List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in [event object](https://docs.stripe.com/api/events/object) api_version attribute (not according to your current Stripe API version or Stripe-Version header). """ result = await cls._static_request_async( "get", diff --git a/stripe/_event_service.py b/stripe/_event_service.py index bb816594f..2cdaf6709 100644 --- a/stripe/_event_service.py +++ b/stripe/_event_service.py @@ -74,7 +74,7 @@ def list( options: RequestOptions = {}, ) -> ListObject[Event]: """ - List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in [event object](https://stripe.com/docs/api/events/object) api_version attribute (not according to your current Stripe API version or Stripe-Version header). + List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in [event object](https://docs.stripe.com/api/events/object) api_version attribute (not according to your current Stripe API version or Stripe-Version header). """ return cast( ListObject[Event], @@ -94,7 +94,7 @@ async def list_async( options: RequestOptions = {}, ) -> ListObject[Event]: """ - List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in [event object](https://stripe.com/docs/api/events/object) api_version attribute (not according to your current Stripe API version or Stripe-Version header). + List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in [event object](https://docs.stripe.com/api/events/object) api_version attribute (not according to your current Stripe API version or Stripe-Version header). """ return cast( ListObject[Event], diff --git a/stripe/_webhook_endpoint.py b/stripe/_webhook_endpoint.py index 86d3f4a57..d5c906baa 100644 --- a/stripe/_webhook_endpoint.py +++ b/stripe/_webhook_endpoint.py @@ -18,13 +18,13 @@ class WebhookEndpoint( UpdateableAPIResource["WebhookEndpoint"], ): """ - You can configure [webhook endpoints](https://stripe.com/docs/webhooks/) via the API to be + You can configure [webhook endpoints](https://docs.stripe.com/webhooks/) via the API to be notified about events that happen in your Stripe account or connected accounts. Most users configure webhooks from [the dashboard](https://dashboard.stripe.com/webhooks), which provides a user interface for registering and testing your webhook endpoints. - Related guide: [Setting up webhooks](https://stripe.com/docs/webhooks/configure) + Related guide: [Setting up webhooks](https://docs.stripe.com/webhooks/configure) """ OBJECT_NAME: ClassVar[Literal["webhook_endpoint"]] = "webhook_endpoint" @@ -776,7 +776,7 @@ class RetrieveParams(RequestOptions): """ secret: Optional[str] """ - The endpoint's secret, used to generate [webhook signatures](https://stripe.com/docs/webhooks/signatures). Only returned at creation. + The endpoint's secret, used to generate [webhook signatures](https://docs.stripe.com/webhooks/signatures). Only returned at creation. """ status: str """ From 9c3e01cf7e26486ce91b1005d6b3c22a3bb21955 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 24 Apr 2024 16:40:18 +0000 Subject: [PATCH 16/21] Update generated code for v987 --- OPENAPI_VERSION | 2 +- stripe/_invoice.py | 6 ++++-- stripe/_invoice_service.py | 4 ++-- stripe/_mandate.py | 10 ++++++++++ stripe/_payment_intent.py | 16 ++++++++++++++++ stripe/_quote_preview_invoice.py | 2 ++ stripe/_setup_attempt.py | 10 ++++++++++ stripe/_subscription.py | 6 ++++-- stripe/_subscription_service.py | 4 ++-- stripe/checkout/_session.py | 18 ++++++++++++++++-- 10 files changed, 67 insertions(+), 11 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 8a5a8933c..f7ad102c1 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v985 \ No newline at end of file +v987 \ No newline at end of file diff --git a/stripe/_invoice.py b/stripe/_invoice.py index 1a647b4e2..3a55de3a1 100644 --- a/stripe/_invoice.py +++ b/stripe/_invoice.py @@ -776,6 +776,7 @@ class FinancialConnections(StripeObject): "ach_credit_transfer", "ach_debit", "acss_debit", + "amazon_pay", "au_becs_debit", "bacs_debit", "bancontact", @@ -794,6 +795,7 @@ class FinancialConnections(StripeObject): "paynow", "paypal", "promptpay", + "revolut_pay", "sepa_credit_transfer", "sepa_debit", "sofort", @@ -1589,7 +1591,7 @@ class CreateParamsPaymentSettings(TypedDict): 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']]" + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'revolut_pay', '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). @@ -4200,7 +4202,7 @@ class ModifyParamsPaymentSettings(TypedDict): 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']]" + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'revolut_pay', '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). diff --git a/stripe/_invoice_service.py b/stripe/_invoice_service.py index 70155031e..f4164ff7e 100644 --- a/stripe/_invoice_service.py +++ b/stripe/_invoice_service.py @@ -555,7 +555,7 @@ class CreateParamsPaymentSettings(TypedDict): 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']]" + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'revolut_pay', '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). @@ -5520,7 +5520,7 @@ class UpdateParamsPaymentSettings(TypedDict): 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']]" + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'revolut_pay', '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). diff --git a/stripe/_mandate.py b/stripe/_mandate.py index 3a948871b..16650f0d4 100644 --- a/stripe/_mandate.py +++ b/stripe/_mandate.py @@ -66,6 +66,9 @@ class AcssDebit(StripeObject): Transaction type of the mandate. """ + class AmazonPay(StripeObject): + pass + class AuBecsDebit(StripeObject): url: str """ @@ -181,6 +184,9 @@ class Payto(StripeObject): Date, in YYYY-MM-DD format, from which payments will be collected. Defaults to confirmation time. """ + class RevolutPay(StripeObject): + pass + class SepaDebit(StripeObject): reference: str """ @@ -198,6 +204,7 @@ class UsBankAccount(StripeObject): """ acss_debit: Optional[AcssDebit] + amazon_pay: Optional[AmazonPay] au_becs_debit: Optional[AuBecsDebit] bacs_debit: Optional[BacsDebit] card: Optional[Card] @@ -205,6 +212,7 @@ class UsBankAccount(StripeObject): link: Optional[Link] paypal: Optional[Paypal] payto: Optional[Payto] + revolut_pay: Optional[RevolutPay] sepa_debit: Optional[SepaDebit] type: str """ @@ -213,6 +221,7 @@ class UsBankAccount(StripeObject): us_bank_account: Optional[UsBankAccount] _inner_class_types = { "acss_debit": AcssDebit, + "amazon_pay": AmazonPay, "au_becs_debit": AuBecsDebit, "bacs_debit": BacsDebit, "card": Card, @@ -220,6 +229,7 @@ class UsBankAccount(StripeObject): "link": Link, "paypal": Paypal, "payto": Payto, + "revolut_pay": RevolutPay, "sepa_debit": SepaDebit, "us_bank_account": UsBankAccount, } diff --git a/stripe/_payment_intent.py b/stripe/_payment_intent.py index 224c563c6..a52c41873 100644 --- a/stripe/_payment_intent.py +++ b/stripe/_payment_intent.py @@ -1367,6 +1367,14 @@ class AmazonPay(StripeObject): """ Controls when the funds will be captured from the customer's account. """ + setup_future_usage: Optional[Literal["none", "off_session"]] + """ + 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 AuBecsDebit(StripeObject): setup_future_usage: Optional[ @@ -2027,6 +2035,14 @@ class RevolutPay(StripeObject): """ Controls when the funds will be captured from the customer's account. """ + setup_future_usage: Optional[Literal["none", "off_session"]] + """ + 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 SepaDebit(StripeObject): class MandateOptions(StripeObject): diff --git a/stripe/_quote_preview_invoice.py b/stripe/_quote_preview_invoice.py index f3fffba2c..31d0bdb18 100644 --- a/stripe/_quote_preview_invoice.py +++ b/stripe/_quote_preview_invoice.py @@ -759,6 +759,7 @@ class FinancialConnections(StripeObject): "ach_credit_transfer", "ach_debit", "acss_debit", + "amazon_pay", "au_becs_debit", "bacs_debit", "bancontact", @@ -777,6 +778,7 @@ class FinancialConnections(StripeObject): "paynow", "paypal", "promptpay", + "revolut_pay", "sepa_credit_transfer", "sepa_debit", "sofort", diff --git a/stripe/_setup_attempt.py b/stripe/_setup_attempt.py index 8517f3712..15c4dbb86 100644 --- a/stripe/_setup_attempt.py +++ b/stripe/_setup_attempt.py @@ -41,6 +41,9 @@ class PaymentMethodDetails(StripeObject): class AcssDebit(StripeObject): pass + class AmazonPay(StripeObject): + pass + class AuBecsDebit(StripeObject): pass @@ -334,6 +337,9 @@ class Paypal(StripeObject): class Payto(StripeObject): pass + class RevolutPay(StripeObject): + pass + class SepaDebit(StripeObject): pass @@ -377,6 +383,7 @@ class UsBankAccount(StripeObject): pass acss_debit: Optional[AcssDebit] + amazon_pay: Optional[AmazonPay] au_becs_debit: Optional[AuBecsDebit] bacs_debit: Optional[BacsDebit] bancontact: Optional[Bancontact] @@ -389,6 +396,7 @@ class UsBankAccount(StripeObject): link: Optional[Link] paypal: Optional[Paypal] payto: Optional[Payto] + revolut_pay: Optional[RevolutPay] sepa_debit: Optional[SepaDebit] sofort: Optional[Sofort] type: str @@ -398,6 +406,7 @@ class UsBankAccount(StripeObject): us_bank_account: Optional[UsBankAccount] _inner_class_types = { "acss_debit": AcssDebit, + "amazon_pay": AmazonPay, "au_becs_debit": AuBecsDebit, "bacs_debit": BacsDebit, "bancontact": Bancontact, @@ -410,6 +419,7 @@ class UsBankAccount(StripeObject): "link": Link, "paypal": Paypal, "payto": Payto, + "revolut_pay": RevolutPay, "sepa_debit": SepaDebit, "sofort": Sofort, "us_bank_account": UsBankAccount, diff --git a/stripe/_subscription.py b/stripe/_subscription.py index c67984b04..17d985663 100644 --- a/stripe/_subscription.py +++ b/stripe/_subscription.py @@ -336,6 +336,7 @@ class FinancialConnections(StripeObject): "ach_credit_transfer", "ach_debit", "acss_debit", + "amazon_pay", "au_becs_debit", "bacs_debit", "bancontact", @@ -354,6 +355,7 @@ class FinancialConnections(StripeObject): "paynow", "paypal", "promptpay", + "revolut_pay", "sepa_credit_transfer", "sepa_debit", "sofort", @@ -1031,7 +1033,7 @@ class CreateParamsPaymentSettings(TypedDict): Payment-method-specific configuration to provide to invoices created by the subscription. """ 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']]" + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'revolut_pay', '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). @@ -1961,7 +1963,7 @@ class ModifyParamsPaymentSettings(TypedDict): Payment-method-specific configuration to provide to invoices created by the subscription. """ 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']]" + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'revolut_pay', '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). diff --git a/stripe/_subscription_service.py b/stripe/_subscription_service.py index a5c4a826a..750ed2fa2 100644 --- a/stripe/_subscription_service.py +++ b/stripe/_subscription_service.py @@ -601,7 +601,7 @@ class CreateParamsPaymentSettings(TypedDict): Payment-method-specific configuration to provide to invoices created by the subscription. """ 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']]" + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'revolut_pay', '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). @@ -1585,7 +1585,7 @@ class UpdateParamsPaymentSettings(TypedDict): Payment-method-specific configuration to provide to invoices created by the subscription. """ 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']]" + "Literal['']|List[Literal['ach_credit_transfer', 'ach_debit', 'acss_debit', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'boleto', 'card', 'cashapp', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'konbini', 'link', 'p24', 'paynow', 'paypal', 'promptpay', 'revolut_pay', '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). diff --git a/stripe/checkout/_session.py b/stripe/checkout/_session.py index 6870ec943..0f9174513 100644 --- a/stripe/checkout/_session.py +++ b/stripe/checkout/_session.py @@ -590,7 +590,14 @@ class Alipay(StripeObject): """ class AmazonPay(StripeObject): - pass + setup_future_usage: Optional[Literal["none", "off_session"]] + """ + 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 AuBecsDebit(StripeObject): setup_future_usage: Optional[Literal["none"]] @@ -901,7 +908,14 @@ class Pix(StripeObject): """ class RevolutPay(StripeObject): - pass + setup_future_usage: Optional[Literal["none", "off_session"]] + """ + 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 SepaDebit(StripeObject): setup_future_usage: Optional[ From 51369b642fad405d10458b06ce2d08ee9da37126 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 24 Apr 2024 18:27:08 +0000 Subject: [PATCH 17/21] Update generated code for v988 --- OPENAPI_VERSION | 2 +- stripe/_capability.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index f7ad102c1..e13775c59 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v987 \ No newline at end of file +v988 \ No newline at end of file diff --git a/stripe/_capability.py b/stripe/_capability.py index 8dc7d3185..d365fc781 100644 --- a/stripe/_capability.py +++ b/stripe/_capability.py @@ -294,13 +294,13 @@ class Error(StripeObject): """ disabled_reason: Optional[str] """ - If the capability is disabled, this string describes why. Can be `requirements.past_due`, `requirements.pending_verification`, `listed`, `platform_paused`, `rejected.fraud`, `rejected.listed`, `rejected.terms_of_service`, `rejected.other`, `under_review`, or `other`. + If the capability is disabled, this string describes why. Can be `requirements.fields_needed`, `pending.onboarding`, `pending.review`, `rejected.fraud`, `rejected.other`, `platform_paused`, `action_required.requested_capabilities`, `rejected.inactivty`, or `rejected.unsupported_business`. - `rejected.unsupported_business` means that the account's business is not supported by the capability. For example, payment methods may restrict the businesses they support in their terms of service: + `rejected.unsupported_business` means that the account's business is not supported by the capability. For example, payment methods may restrict the businesses they support in their terms of service, such as in [Afterpay Clearpay's terms of service](https://stripe.com/afterpay-clearpay/legal#restricted-businesses). - - [Afterpay Clearpay's terms of service](https://stripe.com/afterpay-clearpay/legal#restricted-businesses) + `rejected.inactivity` means that the capability has been paused for inactivity. This disabled reason currently only applies to the Issuing capability. See [Issuing: Managing Inactive Connects](https://support.stripe.com/questions/issuing-managing-inactive-connect-accounts) for more details. - If you believe that the rejection is in error, please contact support at https://support.stripe.com/contact/ for assistance. + If you believe that a rejection is in error, please contact support at https://support.stripe.com/contact/ for assistance. """ errors: List[Error] """ From a288a856fe9a6a876f20d9a12aaca62a403f09de Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Wed, 24 Apr 2024 22:01:49 +0000 Subject: [PATCH 18/21] Update generated code for v989 --- OPENAPI_VERSION | 2 +- stripe/_invoice.py | 4 ++-- stripe/_invoice_service.py | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index e13775c59..811766d23 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v988 \ No newline at end of file +v989 \ No newline at end of file diff --git a/stripe/_invoice.py b/stripe/_invoice.py index 3a55de3a1..c27dd40bb 100644 --- a/stripe/_invoice.py +++ b/stripe/_invoice.py @@ -10516,7 +10516,7 @@ def upcoming(cls, **params: Unpack["Invoice.UpcomingParams"]) -> "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_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_proration_date value passed in the request. + 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", @@ -10536,7 +10536,7 @@ async def upcoming_async( 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_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_proration_date value passed in the request. + 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", diff --git a/stripe/_invoice_service.py b/stripe/_invoice_service.py index f4164ff7e..be5fb70c2 100644 --- a/stripe/_invoice_service.py +++ b/stripe/_invoice_service.py @@ -6198,7 +6198,7 @@ def upcoming( 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_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_proration_date value passed in the request. + 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, @@ -6222,7 +6222,7 @@ async def upcoming_async( 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_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_proration_date value passed in the request. + 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, From d9a61ff6f3bf74f17b0d7616c1b12ffc726a6c96 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Thu, 25 Apr 2024 00:11:17 +0000 Subject: [PATCH 19/21] Update generated code for v990 --- OPENAPI_VERSION | 2 +- stripe/_account.py | 4 ++-- stripe/_account_service.py | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 811766d23..16c0892c2 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v989 \ No newline at end of file +v990 \ No newline at end of file diff --git a/stripe/_account.py b/stripe/_account.py index 370a9f5c1..806a2728d 100644 --- a/stripe/_account.py +++ b/stripe/_account.py @@ -603,7 +603,7 @@ class Fees(StripeObject): "application_unified_accounts_beta", ] """ - A value indicating the responsible payer of a bundle of Stripe fees for pricing-control eligible products on this account. + A value indicating the responsible payer of a bundle of Stripe fees for pricing-control eligible products on this account. Learn more about [fee behavior on connected accounts](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior). """ class Losses(StripeObject): @@ -2250,7 +2250,7 @@ class CreateParamsControllerDashboard(TypedDict): class CreateParamsControllerFees(TypedDict): payer: NotRequired[Literal["account", "application"]] """ - A value indicating the responsible payer of Stripe fees on this account. Defaults to `account`. + A value indicating the responsible payer of Stripe fees on this account. Defaults to `account`. Learn more about [fee behavior on connected accounts](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior). """ class CreateParamsControllerLosses(TypedDict): diff --git a/stripe/_account_service.py b/stripe/_account_service.py index 67e69811a..4142cdca5 100644 --- a/stripe/_account_service.py +++ b/stripe/_account_service.py @@ -1045,7 +1045,7 @@ class CreateParamsControllerDashboard(TypedDict): class CreateParamsControllerFees(TypedDict): payer: NotRequired[Literal["account", "application"]] """ - A value indicating the responsible payer of Stripe fees on this account. Defaults to `account`. + A value indicating the responsible payer of Stripe fees on this account. Defaults to `account`. Learn more about [fee behavior on connected accounts](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior). """ class CreateParamsControllerLosses(TypedDict): From 8856041fcad2fb55bc0d2b7849fe0e9e1e26c17c Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Thu, 25 Apr 2024 01:15:28 +0000 Subject: [PATCH 20/21] Update generated code for v991 --- OPENAPI_VERSION | 2 +- stripe/_price.py | 2 +- stripe/_price_service.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 16c0892c2..00ab57870 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v990 \ No newline at end of file +v991 \ No newline at end of file diff --git a/stripe/_price.py b/stripe/_price.py index 9be70b821..267747758 100644 --- a/stripe/_price.py +++ b/stripe/_price.py @@ -276,7 +276,7 @@ class CreateParams(RequestOptions): """ unit_amount: NotRequired[int] """ - A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. One of `unit_amount` or `custom_unit_amount` is required, unless `billing_scheme=tiered`. + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. One of `unit_amount`, `unit_amount_decimal`, or `custom_unit_amount` is required, unless `billing_scheme=tiered`. """ unit_amount_decimal: NotRequired[str] """ diff --git a/stripe/_price_service.py b/stripe/_price_service.py index b4e49e767..07bb02caf 100644 --- a/stripe/_price_service.py +++ b/stripe/_price_service.py @@ -90,7 +90,7 @@ class CreateParams(TypedDict): """ unit_amount: NotRequired[int] """ - A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. One of `unit_amount` or `custom_unit_amount` is required, unless `billing_scheme=tiered`. + A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. One of `unit_amount`, `unit_amount_decimal`, or `custom_unit_amount` is required, unless `billing_scheme=tiered`. """ unit_amount_decimal: NotRequired[str] """ From 119e6fc1cf5216e8ef33991f593ae76a3b0a35b4 Mon Sep 17 00:00:00 2001 From: Stripe OpenAPI <105521251+stripe-openapi[bot]@users.noreply.github.com> Date: Thu, 25 Apr 2024 18:24:54 +0000 Subject: [PATCH 21/21] Update generated code for v992 --- OPENAPI_VERSION | 2 +- stripe/_payment_method_configuration.py | 64 +++++++++++++++++++ .../_payment_method_configuration_service.py | 40 ++++++++++++ 3 files changed, 105 insertions(+), 1 deletion(-) diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 00ab57870..6eb80deb2 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v991 \ No newline at end of file +v992 \ No newline at end of file diff --git a/stripe/_payment_method_configuration.py b/stripe/_payment_method_configuration.py index a4f3d27ac..2f4da96cd 100644 --- a/stripe/_payment_method_configuration.py +++ b/stripe/_payment_method_configuration.py @@ -587,6 +587,28 @@ class DisplayPreference(StripeObject): display_preference: DisplayPreference _inner_class_types = {"display_preference": DisplayPreference} + class Mobilepay(StripeObject): + class DisplayPreference(StripeObject): + overridable: Optional[bool] + """ + For child configs, whether or not the account's preference will be observed. If `false`, the parent configuration's default is used. + """ + preference: Literal["none", "off", "on"] + """ + The account's display preference. + """ + value: Literal["off", "on"] + """ + The effective display preference value. + """ + + available: bool + """ + Whether this payment method may be offered at checkout. True if `display_preference` is `on` and the payment method's capability is active. + """ + display_preference: DisplayPreference + _inner_class_types = {"display_preference": DisplayPreference} + class Multibanco(StripeObject): class DisplayPreference(StripeObject): overridable: Optional[bool] @@ -1004,6 +1026,12 @@ class CreateParams(RequestOptions): """ [Link](https://stripe.com/docs/payments/link) is a payment method network. With Link, users save their payment details once, then reuse that information to pay with one click for any business on the network. """ + mobilepay: NotRequired[ + "PaymentMethodConfiguration.CreateParamsMobilepay" + ] + """ + MobilePay is a [single-use](https://stripe.com/docs/payments/payment-methods#usage) card wallet payment method used in Denmark and Finland. It allows customers to [authenticate and approve](https://stripe.com/docs/payments/payment-methods#customer-actions) payments using the MobilePay app. Check this [page](https://stripe.com/docs/payments/mobilepay) for more details. + """ multibanco: NotRequired[ "PaymentMethodConfiguration.CreateParamsMultibanco" ] @@ -1441,6 +1469,20 @@ class CreateParamsLinkDisplayPreference(TypedDict): The account's preference for whether or not to display this payment method. """ + class CreateParamsMobilepay(TypedDict): + display_preference: NotRequired[ + "PaymentMethodConfiguration.CreateParamsMobilepayDisplayPreference" + ] + """ + Whether or not the payment method should be displayed. + """ + + class CreateParamsMobilepayDisplayPreference(TypedDict): + preference: NotRequired[Literal["none", "off", "on"]] + """ + The account's preference for whether or not to display this payment method. + """ + class CreateParamsMultibanco(TypedDict): display_preference: NotRequired[ "PaymentMethodConfiguration.CreateParamsMultibancoDisplayPreference" @@ -1780,6 +1822,12 @@ class ModifyParams(RequestOptions): """ [Link](https://stripe.com/docs/payments/link) is a payment method network. With Link, users save their payment details once, then reuse that information to pay with one click for any business on the network. """ + mobilepay: NotRequired[ + "PaymentMethodConfiguration.ModifyParamsMobilepay" + ] + """ + MobilePay is a [single-use](https://stripe.com/docs/payments/payment-methods#usage) card wallet payment method used in Denmark and Finland. It allows customers to [authenticate and approve](https://stripe.com/docs/payments/payment-methods#customer-actions) payments using the MobilePay app. Check this [page](https://stripe.com/docs/payments/mobilepay) for more details. + """ multibanco: NotRequired[ "PaymentMethodConfiguration.ModifyParamsMultibanco" ] @@ -2213,6 +2261,20 @@ class ModifyParamsLinkDisplayPreference(TypedDict): The account's preference for whether or not to display this payment method. """ + class ModifyParamsMobilepay(TypedDict): + display_preference: NotRequired[ + "PaymentMethodConfiguration.ModifyParamsMobilepayDisplayPreference" + ] + """ + Whether or not the payment method should be displayed. + """ + + class ModifyParamsMobilepayDisplayPreference(TypedDict): + preference: NotRequired[Literal["none", "off", "on"]] + """ + The account's preference for whether or not to display this payment method. + """ + class ModifyParamsMultibanco(TypedDict): display_preference: NotRequired[ "PaymentMethodConfiguration.ModifyParamsMultibancoDisplayPreference" @@ -2446,6 +2508,7 @@ class RetrieveParams(RequestOptions): """ Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode. """ + mobilepay: Optional[Mobilepay] multibanco: Optional[Multibanco] name: str """ @@ -2636,6 +2699,7 @@ async def retrieve_async( "klarna": Klarna, "konbini": Konbini, "link": Link, + "mobilepay": Mobilepay, "multibanco": Multibanco, "oxxo": Oxxo, "p24": P24, diff --git a/stripe/_payment_method_configuration_service.py b/stripe/_payment_method_configuration_service.py index 15c48ace8..3b639f873 100644 --- a/stripe/_payment_method_configuration_service.py +++ b/stripe/_payment_method_configuration_service.py @@ -159,6 +159,12 @@ class CreateParams(TypedDict): """ [Link](https://stripe.com/docs/payments/link) is a payment method network. With Link, users save their payment details once, then reuse that information to pay with one click for any business on the network. """ + mobilepay: NotRequired[ + "PaymentMethodConfigurationService.CreateParamsMobilepay" + ] + """ + MobilePay is a [single-use](https://stripe.com/docs/payments/payment-methods#usage) card wallet payment method used in Denmark and Finland. It allows customers to [authenticate and approve](https://stripe.com/docs/payments/payment-methods#customer-actions) payments using the MobilePay app. Check this [page](https://stripe.com/docs/payments/mobilepay) for more details. + """ multibanco: NotRequired[ "PaymentMethodConfigurationService.CreateParamsMultibanco" ] @@ -604,6 +610,20 @@ class CreateParamsLinkDisplayPreference(TypedDict): The account's preference for whether or not to display this payment method. """ + class CreateParamsMobilepay(TypedDict): + display_preference: NotRequired[ + "PaymentMethodConfigurationService.CreateParamsMobilepayDisplayPreference" + ] + """ + Whether or not the payment method should be displayed. + """ + + class CreateParamsMobilepayDisplayPreference(TypedDict): + preference: NotRequired[Literal["none", "off", "on"]] + """ + The account's preference for whether or not to display this payment method. + """ + class CreateParamsMultibanco(TypedDict): display_preference: NotRequired[ "PaymentMethodConfigurationService.CreateParamsMultibancoDisplayPreference" @@ -967,6 +987,12 @@ class UpdateParams(TypedDict): """ [Link](https://stripe.com/docs/payments/link) is a payment method network. With Link, users save their payment details once, then reuse that information to pay with one click for any business on the network. """ + mobilepay: NotRequired[ + "PaymentMethodConfigurationService.UpdateParamsMobilepay" + ] + """ + MobilePay is a [single-use](https://stripe.com/docs/payments/payment-methods#usage) card wallet payment method used in Denmark and Finland. It allows customers to [authenticate and approve](https://stripe.com/docs/payments/payment-methods#customer-actions) payments using the MobilePay app. Check this [page](https://stripe.com/docs/payments/mobilepay) for more details. + """ multibanco: NotRequired[ "PaymentMethodConfigurationService.UpdateParamsMultibanco" ] @@ -1408,6 +1434,20 @@ class UpdateParamsLinkDisplayPreference(TypedDict): The account's preference for whether or not to display this payment method. """ + class UpdateParamsMobilepay(TypedDict): + display_preference: NotRequired[ + "PaymentMethodConfigurationService.UpdateParamsMobilepayDisplayPreference" + ] + """ + Whether or not the payment method should be displayed. + """ + + class UpdateParamsMobilepayDisplayPreference(TypedDict): + preference: NotRequired[Literal["none", "off", "on"]] + """ + The account's preference for whether or not to display this payment method. + """ + class UpdateParamsMultibanco(TypedDict): display_preference: NotRequired[ "PaymentMethodConfigurationService.UpdateParamsMultibancoDisplayPreference"