Migration guide for v14 and v15

The v14 and v15 of the Ruby SDK uses the API version 2025-03-31.basil. If the format of this API version looks new to you, see our new API release process

v15 makes one breaking change over v14. If you are using the RequestParams object Stripe::V2::Core::EventService::ListParams, the field object_id has been renamed to object_id_. We recommend using v15 to avoid overwriting Ruby's native object_id for this parameter.

The new API version comes with a quite a few breaking changes, most notably:

• Billing changes: We removed or reorganized a number of capabilities, including legacy usage-based billing and a migration from the Upcoming Invoice API to the Create Preview API. Many of these breaking changes are preparing our APIs for future updates later this year in the Basil release.
• Total counts no longer supported on lists: You can no longer expand the total_count property on lists, because this is no longer a recommended integration pattern.
• Checkout Sessions for subscriptions now postpone creation of subscriptions until after the user completes payment—this both improves latency on all Checkout Session API calls and fixes a common bug where customers couldn’t modify billing details after the first payment attempt.

Please review our API changelog for 2025-03-31.basil to understand all the breaking changes to the Stripe API, the reasons behind them and potential alternatives.

The Ruby SDK specific changelog for v14 will have the corresponding changes in the SDKs as well as SDK specific breaking changes.

We have also added static type annotations in this release, so do check it out!