Migration guide for v16

The v16 of the Ruby SDK uses the API version 2025-09-30.clover. If the format of this API version looks new to you, see our new API release process

The new API version comes with a few SDK-specific breaking changes, most notably:

• Params changes: We've combined parameter types for resource and service types. More details are available below.
• V2 Events: We've overhauled how V2 Events are handled in the SDK, and moved them under Stripe::V2::Core to mirror the API. This approach should provide a lot more information at authoring and compile time, leading to more robust integrations. As part of this process, there are a number of changes to be aware of. The changelog has explicit details of breaking changes, and an example for how to use our new events pattern is available.
• Drop support for Ruby 2.3-2.5: We have published a new language support policy and dropped support for Ruby 2.3-2.5. A schedule for future deprecations has also been provided.

Please review our API changelog for 2025-09-30.clover to understand all the breaking changes to the Stripe API, the reasons behind them and potential alternatives.

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

Parameter type unification

Resource and service parameters have been unified to increase consistency and decrease package size in this major. Parameters have been moved to the top-level Stripe module and prefixed with the relevant resource/service and method name.

For example, Stripe::CustomerService::CreateParams is now Stripe::CustomerCreateParams. There are no changes necessary if you do not use parameter types, and instead use hashes:

require 'stripe'

client = Stripe::StripeClient.new(API_KEY)
client.v1.customers.create({
  name: "Foo",
  email: "[email protected]"
})

If you use parameter types directly, you will need to update the types. For example:

## Before
require 'stripe'

client = Stripe::StripeClient.new(API_KEY)
params = Stripe::CustomerService::CreateParams.new(
  name: "Foo",
  email: "[email protected]"
)
client.v1.customers.create(params)


## After
require 'stripe'

client = Stripe::StripeClient.new(API_KEY)
params = Stripe::CustomerCreateParams.new(
  name: "Foo",
  email: "[email protected]"
)
client.v1.customers.create(params)