Migration guide for v16

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.

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.

The Python SDK specific changelog for v16 has the corresponding changes in the SDKs as well as SDK specific breaking changes.

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:

# 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:

# 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:

customer = client.v1.customers.retrieve(customer="cus_123")

must now be passed positionally:

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:

# 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.