Update generated code for beta

OPENAPI_VERSION

@@ -1 +1 @@
-v840
+v857

README.md

@@ -33,7 +33,7 @@ python setup.py install
 
 ### Requirements
 
-- Python 3.6+ (PyPy supported)
+-   Python 3.6+ (PyPy supported)
 
 #### Python 2.7 deprecation
 
@@ -228,9 +228,9 @@ is anything we can do to improve the types for your type checker of choice.
 ### Types and the Versioning Policy
 
 We release type changes in minor releases. While stripe-python follows semantic
-versioning, our semantic versions describe the *runtime behavior* of the
-library alone. Our *type annotations are not reflected in the semantic
-version*. That is, upgrading to a new minor version of stripe-python might
+versioning, our semantic versions describe the _runtime behavior_ of the
+library alone. Our _type annotations are not reflected in the semantic
+version_. That is, upgrading to a new minor version of stripe-python might
 result in your type checker producing a type error that it didn't before. You
 can use a `~=x.x` or `x.x.*` [version specifier](https://peps.python.org/pep-0440/#examples)
 in your `requirements.txt` to constrain `pip` to a certain minor range of `stripe-python`.
@@ -258,10 +258,10 @@ pip install stripe==5.3.0b3
 
 We highly recommend keeping an eye on when the beta feature you are interested in goes from beta to stable so that you can move from using a beta version of the SDK to the stable version.
 
-If your beta feature requires a `Stripe-Version` header to be sent, use the `stripe.api_version` field to set it:
+If your beta feature requires a `Stripe-Version` header to be sent, set the `stripe.api_version` field using the `stripe.add_beta_version` function:
 
 ```python
-stripe.api_version += "; feature_beta=v3"
+stripe.add_beta_version("feature_beta", "v3")
 ```
 
 ### Custom requests

stripe/_bank_account.py

@@ -355,7 +355,7 @@ class DeleteParams(RequestOptions):
     """
     For bank accounts, possible values are `new`, `validated`, `verified`, `verification_failed`, or `errored`. A bank account that hasn't had any activity or validation performed is `new`. If Stripe can determine that the bank account exists, its status will be `validated`. Note that there often isn't enough information to know (e.g., for smaller credit unions), and the validation is not always run. If customer bank account verification has succeeded, the bank account status will be `verified`. If the verification failed for any reason, such as microdeposit failure, the status will be `verification_failed`. If a payout sent to this bank account fails, we'll set the status to `errored` and will not continue to send [scheduled payouts](https://stripe.com/docs/payouts#payout-schedule) until the bank details are updated.
 
-    For external accounts, possible values are `new`, `errored` and `verification_failed`. If a payouts fails, the status is set to `errored` and scheduled payouts are stopped until account details are updated. In India, if we can't [verify the owner of the bank account](https://support.stripe.com/questions/bank-account-ownership-verification), we'll set the status to `verification_failed`. Other validations aren't run against external accounts because they're only used for payouts. This means the other statuses don't apply.
+    For external accounts, possible values are `new`, `errored` and `verification_failed`. If a payout fails, the status is set to `errored` and scheduled payouts are stopped until account details are updated. In the US and India, if we can't [verify the owner of the bank account](https://support.stripe.com/questions/bank-account-ownership-verification), we'll set the status to `verification_failed`. Other validations aren't run against external accounts because they're only used for payouts. This means the other statuses don't apply.
     """
     deleted: Optional[Literal[True]]
     """

stripe/_charge.py

@@ -4,6 +4,7 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
+from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._request_options import RequestOptions
 from stripe._search_result_object import SearchResultObject
 from stripe._searchable_api_resource import SearchableAPIResource
@@ -47,6 +48,7 @@
     from stripe._transfer import Transfer
 
 
+@nested_resource_class_methods("refund")
 class Charge(
     CreateableAPIResource["Charge"],
     ListableAPIResource["Charge"],
@@ -2675,6 +2677,24 @@ class ListParamsCreated(TypedDict):
         Maximum value to filter by (inclusive)
         """
 
+    class ListRefundsParams(RequestOptions):
+        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):
         customer: NotRequired["str"]
         """
@@ -3403,6 +3423,12 @@ class RetrieveParams(RequestOptions):
         Specifies which fields in the response should be expanded.
         """
 
+    class RetrieveRefundParams(RequestOptions):
+        expand: NotRequired["List[str]"]
+        """
+        Specifies which fields in the response should be expanded.
+        """
+
     class SearchParams(RequestOptions):
         expand: NotRequired["List[str]"]
         """
@@ -3938,6 +3964,84 @@ def mark_as_safe(self, idempotency_key=None) -> "Charge":
         self._request_and_refresh("post", url, params)
         return self
 
+    @classmethod
+    def retrieve_refund(
+        cls,
+        charge: str,
+        refund: str,
+        **params: Unpack["Charge.RetrieveRefundParams"]
+    ) -> "Refund":
+        """
+        Retrieves the details of an existing refund.
+        """
+        return cast(
+            "Refund",
+            cls._static_request(
+                "get",
+                "/v1/charges/{charge}/refunds/{refund}".format(
+                    charge=sanitize_id(charge), refund=sanitize_id(refund)
+                ),
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def retrieve_refund_async(
+        cls,
+        charge: str,
+        refund: str,
+        **params: Unpack["Charge.RetrieveRefundParams"]
+    ) -> "Refund":
+        """
+        Retrieves the details of an existing refund.
+        """
+        return cast(
+            "Refund",
+            await cls._static_request_async(
+                "get",
+                "/v1/charges/{charge}/refunds/{refund}".format(
+                    charge=sanitize_id(charge), refund=sanitize_id(refund)
+                ),
+                params=params,
+            ),
+        )
+
+    @classmethod
+    def list_refunds(
+        cls, charge: str, **params: Unpack["Charge.ListRefundsParams"]
+    ) -> ListObject["Refund"]:
+        """
+        You can see a list of the refunds belonging to a specific charge. Note that the 10 most recent refunds are always available by default on the charge object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional refunds.
+        """
+        return cast(
+            ListObject["Refund"],
+            cls._static_request(
+                "get",
+                "/v1/charges/{charge}/refunds".format(
+                    charge=sanitize_id(charge)
+                ),
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def list_refunds_async(
+        cls, charge: str, **params: Unpack["Charge.ListRefundsParams"]
+    ) -> ListObject["Refund"]:
+        """
+        You can see a list of the refunds belonging to a specific charge. Note that the 10 most recent refunds are always available by default on the charge object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional refunds.
+        """
+        return cast(
+            ListObject["Refund"],
+            await cls._static_request_async(
+                "get",
+                "/v1/charges/{charge}/refunds".format(
+                    charge=sanitize_id(charge)
+                ),
+                params=params,
+            ),
+        )
+
     _inner_class_types = {
         "billing_details": BillingDetails,
         "fraud_details": FraudDetails,

stripe/_customer_entitlement.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # File generated from our OpenAPI spec
 from stripe._stripe_object import StripeObject
-from typing import ClassVar, Optional
+from typing import ClassVar
 from typing_extensions import Literal
 
 
@@ -13,13 +13,6 @@ class CustomerEntitlement(StripeObject):
     OBJECT_NAME: ClassVar[
         Literal["customer_entitlement"]
     ] = "customer_entitlement"
-
-    class Quantity(StripeObject):
-        total_available: int
-        """
-        The total quantity available to the customer.
-        """
-
     feature: str
     """
     The feature that the customer is entitled to.
@@ -40,12 +33,3 @@ class Quantity(StripeObject):
     """
     String representing the object's type. Objects of the same type share the same value.
     """
-    quantity: Optional[Quantity]
-    """
-    Contains information about entitlements relating to features with type=quantity. Required when the feature has type=quantity.
-    """
-    type: Literal["quantity", "switch"]
-    """
-    The type of feature.
-    """
-    _inner_class_types = {"quantity": Quantity}

stripe/_entitlements_service.py

@@ -1,12 +1,10 @@
 # -*- coding: utf-8 -*-
 # File generated from our OpenAPI spec
 from stripe._stripe_service import StripeService
-from stripe.entitlements._event_service import EventService
 from stripe.entitlements._feature_service import FeatureService
 
 
 class EntitlementsService(StripeService):
     def __init__(self, requestor):
         super().__init__(requestor)
-        self.events = EventService(self._requestor)
         self.features = FeatureService(self._requestor)

stripe/_invoice.py

@@ -1162,6 +1162,10 @@ class CreateParams(RequestOptions):
         """
         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["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["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.
@@ -2846,7 +2850,7 @@ class CreatePreviewParamsScheduleDetailsPhase(TypedDict):
         """
         coupon: NotRequired["str"]
         """
-        The identifier of the coupon to apply to this phase of the subscription schedule.
+        The identifier 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"]
         """
@@ -3960,6 +3964,10 @@ class ModifyParams(RequestOptions):
         """
         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.
@@ -5710,7 +5718,7 @@ class UpcomingLinesParamsScheduleDetailsPhase(TypedDict):
         """
         coupon: NotRequired["str"]
         """
-        The identifier of the coupon to apply to this phase of the subscription schedule.
+        The identifier 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"]
         """
@@ -7727,7 +7735,7 @@ class UpcomingParamsScheduleDetailsPhase(TypedDict):
         """
         coupon: NotRequired["str"]
         """
-        The identifier of the coupon to apply to this phase of the subscription schedule.
+        The identifier 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"]
         """

stripe/_invoice_service.py

@@ -135,6 +135,10 @@ class CreateParams(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`.
         """
+        number: NotRequired["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["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.
@@ -1833,7 +1837,7 @@ class CreatePreviewParamsScheduleDetailsPhase(TypedDict):
         """
         coupon: NotRequired["str"]
         """
-        The identifier of the coupon to apply to this phase of the subscription schedule.
+        The identifier 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"]
         """
@@ -4026,7 +4030,7 @@ class UpcomingParamsScheduleDetailsPhase(TypedDict):
         """
         coupon: NotRequired["str"]
         """
-        The identifier of the coupon to apply to this phase of the subscription schedule.
+        The identifier 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"]
         """
@@ -4998,6 +5002,10 @@ class UpdateParams(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`.
         """
+        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.

stripe/_invoice_upcoming_lines_service.py

@@ -1137,7 +1137,7 @@ class ListParamsScheduleDetailsPhase(TypedDict):
         """
         coupon: NotRequired["str"]
         """
-        The identifier of the coupon to apply to this phase of the subscription schedule.
+        The identifier 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"]
         """

stripe/_object_classes.py

@@ -46,7 +46,6 @@
     stripe.CustomerSession.OBJECT_NAME: stripe.CustomerSession,
     stripe.Discount.OBJECT_NAME: stripe.Discount,
     stripe.Dispute.OBJECT_NAME: stripe.Dispute,
-    stripe.entitlements.Event.OBJECT_NAME: stripe.entitlements.Event,
     stripe.entitlements.Feature.OBJECT_NAME: stripe.entitlements.Feature,
     stripe.EphemeralKey.OBJECT_NAME: stripe.EphemeralKey,
     stripe.Event.OBJECT_NAME: stripe.Event,