Changes for upcoming major release

.hark/changes/2026-09-17_zacchua_remove-deprecated-stripeobject-request.change.md

@@ -0,0 +1,7 @@
+---
+title: Remove deprecated `StripeObject.request()` method
+pr_url: https://github.com/stripe/stripe-python/pull/1914
+semver_level: major
+---
+
+The deprecated `StripeObject.request()` method has been removed. Use `StripeClient.raw_request()` to make custom API requests.

.hark/changes/2026-09-17_zacchua_rename-reversal-transferreversal.change.md

@@ -0,0 +1,7 @@
+---
+title: Rename `stripe.Reversal` to `stripe.TransferReversal`
+pr_url: https://github.com/stripe/stripe-python/pull/1915
+semver_level: major
+---
+
+- ⚠️ Rename the `stripe.Reversal` resource class to `stripe.TransferReversal`. Update references and type annotations to use `stripe.TransferReversal`.

.hark/changes/2026-09-18_markisaackogan_mark-path-params-as-positional-only.change.md

@@ -0,0 +1,9 @@
+---
+title: Make path parameters positional-only in all service methods
+pr_url: https://github.com/stripe/stripe-python/pull/1920
+semver_level: major
+---
+
+Path parameters must now be passed positionally to service methods. Passing them by keyword is no longer supported. This prevents parameter names derived from the API specification from becoming part of the public interface.
+
+ Resource methods are unaffected by this change.

.hark/changes/2026-09-23_markisaackogan_mark-overloaded-params-as-positional-only.change.md

@@ -0,0 +1,7 @@
+---
+title: Make path parameters positional-only in all service methods
+pr_url: https://github.com/stripe/stripe-python/pull/1924
+semver_level: major
+---
+
+ Path parameters must now be passed positionally on resource methods that support both classmethod and instance-method call styles (e.g. Coupon.delete). Passing them by keyword is no longer supported. 

.hark/migration-guides/v16.md

@@ -0,0 +1,78 @@
+# Migration guide for v16
+
+This version of the SDK uses API version `2026-09-30.endive`. If the format of this API version looks new to you, see our new [API release process](https://stripe.com/blog/introducing-stripes-new-api-release-process).
+
+Please review our API changelog for `2026-09-30.endive` to understand all the breaking changes to the Stripe API, the reasons behind them and potential alternatives.
+
+<!-- This is the migration guide for the next major version!
+If you're making breaking changes, add a new h2 header with a nice title and write a detailed guide to help users upgrade.
+You will almost certainly need before/after code examples and information about which users this change affects.
+See: https://github.com/stripe/hark#writing-a-great-migration-guide
+-->
+
+## Rename `stripe.Reversal` to `stripe.TransferReversal`
+
+The class representing a transfer reversal has been renamed from `stripe.Reversal` to `stripe.TransferReversal`.
+
+This change affects integrations that reference `stripe.Reversal` directly, including imports, class comparisons, `isinstance` checks, and type annotations. Replace those references with `stripe.TransferReversal`:
+
+```python
+# Before
+reversal = stripe.Transfer.retrieve_reversal("tr_123", "trr_123")
+isinstance(reversal, stripe.Reversal)
+
+# After
+reversal = stripe.Transfer.retrieve_reversal("tr_123", "trr_123")
+isinstance(reversal, stripe.TransferReversal)
+```
+
+The methods for creating, retrieving, modifying, and listing transfer reversals have not changed. Code that only calls those methods and reads attributes from the returned object does not require an update.
+
+## `StripeObject.request()` has been removed
+
+The deprecated `StripeObject.request()` method has been removed. If you used it to make custom API requests, create a `StripeClient` and use `raw_request()` instead:
+
+```python
+# Before
+response = stripe_object.request("get", "/v1/example")
+
+# After
+client = stripe.StripeClient("sk_test_...")
+response = client.raw_request("get", "/v1/example")
+```
+
+## Path parameters must now be passed positionally
+
+Path parameters must now be passed positionally instead of by keyword.
+
+For example, a customer ID that was previously accepted as a keyword argument:
+
+```python
+customer = client.v1.customers.retrieve(customer="cus_123")
+```
+
+must now be passed positionally:
+
+```python
+customer = client.v1.customers.retrieve("cus_123")
+```
+
+This also affects legacy resource methods that support both classmethod and instance-method call styles. For example, `Customer.retrieve_payment_method`:
+
+```python
+# Before
+payment_method = customer.retrieve_payment_method(
+    payment_method="pm_123"
+)
+payment_method = stripe.Customer.retrieve_payment_method(
+    customer="cus_123", payment_method="pm_123"
+)
+
+# After
+payment_method = customer.retrieve_payment_method("pm_123")
+payment_method = stripe.Customer.retrieve_payment_method(
+    "cus_123", "pm_123"
+)
+```
+
+Update calls to your methods to pass path parameters before any request parameters or options.

CHANGELOG.md

@@ -5,6 +5,16 @@ Instead, edit a corresponding `.change.md` file and run `hark build`.
 
 # Changelog
 
+## Unreleased
+* [#1904](https://github.com/stripe/stripe-python/pull/1904) Support `EventNotification`s with singleton related objects
+* [#1909](https://github.com/stripe/stripe-python/pull/1909) Allow suppressing Stripe notices
+  Set the `STRIPE_SUPPRESS_NOTICES` environment variable to `true` to suppress Stripe notices in test and sandbox environments when not running under a detected AI agent. Notices remain enabled by default and continue to be shown to AI agents.
+* [#1911](https://github.com/stripe/stripe-python/pull/1911) Fix account scoping for event notification handler callback clients
+  - Fix callback clients to use the event's Stripe context and preserve the original client's non-account configuration.
+  - Fix API errors when using an event notification handler with a client configured with a Stripe account.
+* ⚠️ [#1919](https://github.com/stripe/stripe-python/pull/1919) Make path parameters positional-only in all service methods
+  Path parameters must now be passed positionally to service methods. Passing them by keyword is no longer supported.  Resource methods are unaffected by this change.
+
 ## <a id="15-6-1"></a>15.6.1 - 2026-09-01
 * [#1860](https://github.com/stripe/stripe-python/pull/1860) Dispatch discriminated union fields to their variant class
 * [#1896](https://github.com/stripe/stripe-python/pull/1896) Harden API requestor code against malicious URLs

pyproject.toml

@@ -76,7 +76,7 @@ reportUnnecessaryComparison = true
 reportUnnecessaryContains = true
 reportUnnecessaryIsInstance = true
 reportPrivateImportUsage = true
-reportUnnecessaryTypeIgnoreComment = false
+reportUnnecessaryTypeIgnoreComment = true
 
 [tool.mypy]
 follow_imports = "silent"

stripe/__init__.py

@@ -447,7 +447,7 @@ def set_app_info(
     from stripe._reserve_transaction import (
         ReserveTransaction as ReserveTransaction,
     )
-    from stripe._reversal import Reversal as Reversal
+    from stripe._transfer_reversal import TransferReversal as TransferReversal
     from stripe._review import Review as Review
     from stripe._review_service import ReviewService as ReviewService
     from stripe._search_result_object import (
@@ -835,7 +835,7 @@ def set_app_info(
     "RequestOptions": ("stripe._request_options", False),
     "RequestorOptions": ("stripe._requestor_options", False),
     "ReserveTransaction": ("stripe._reserve_transaction", False),
-    "Reversal": ("stripe._reversal", False),
+    "TransferReversal": ("stripe._transfer_reversal", False),
     "Review": ("stripe._review", False),
     "ReviewService": ("stripe._review_service", False),
     "SearchResultObject": ("stripe._search_result_object", False),