-
Notifications
You must be signed in to change notification settings - Fork 544
Migration guide for v13
In stripe-ruby v13, we have renamed the StripeClient
requestor interface to APIRequestor
and repurposed the StripeClient
name for a new class as an entry-point to the service-based call pattern. This new interface allows you to easily call Stripe APIs and has several benefits over the existing resource-based pattern:
- No global config: you can simultaneously use multiple clients with different configuration options (such as API keys)
- No extra API calls. All API endpoints can be accessed with a single method call. You don't have to call retrieve before doing an update.
- No static methods for easier mocking
To migrate from a resource-based to service-based pattern:
-
Initialize a
StripeClient
instance. It is required to pass an api key as the first positional argument of StripeClient.Before
Stripe.api_key = "sk_test_123"
After
client = Stripe::StripeClient.new("sk_test_123")
You can also pass in previously configurable global options as keyword arguments into the
StripeClient
constructor (link TKTK). For configurable options that are not specified or not currently available onStripeClient
, we fall back to the globalStripeConfiguration
.Before
Stripe.api_key = "sk_test_123" Stripe.api_version = "2022-11-15"
After
client = Stripe::StripeClient.new( "sk_test_123", stripe_version: "2022-11-15", )
-
Convert class resource method calls to
StripeClient
calls. Parameters and options are still passed in the same way as in the resource-based pattern. Services are available under either thev1
orv2
accessors.Before
customer = Stripe::Customer.create({email: "jenny.rosen@example.com"}, {stripe_account: "acct_123"})
After
customer = client.v1.customers.create({email: "jenny.rosen@example.com"}, {stripe_account: "acct_123"})
-
Convert instance resource method calls to
StripeClient
calls.Before
customer = Stripe::Customer.retrieve("cus_123"); customer.delete();
After
client.v1.customers.delete("cus_123");
-
Convert nested resource operations to
StripeClient
calls.Before
Stripe::Customer.list_balance_transactions( "cus_123", {limit: 3}, {stripe_version: "2022-11-15"} )
After
customer = client.v1.customers.balance_transactions.list( "cus_123", {"limit": 3}, {"stripe_version": "2022-11-15"}, );
request
is still available for StripeClient, though it is deprecated and will be removed in a future version. It is backed by APIRequestor.request
, which has the same behavior as in previous versions. We suggest migrating to StripeClient.raw_request
and StripeClient.deserialize
if you need to make custom requests:
Before
client = StripeClient.new
charge, resp = client.request { Charge.create }
After
client = StripeClient.new("sk_test_123")
resp = client.raw_request(:post, "/v1/charges")
charge = client.deserialize(resp.data)
If you need to pass params and to raw_request
, pass them in as keyword arguments:
resp = client.raw_request(
:post,
"/v1/charges",
params: {
amount: 4242,
currency: "usd",
source: tok_visa",
}, opts: {
stripe_account: "acct_123"
})
If you need the raw StripeResponse
instead, you can access it via the last_response
property on deserialized objects:
charge = client.v1.charges.create(...)
charge.last_response
- Adjust default values around retries for HTTP requests. You can use the old defaults by setting them explicitly. New values are:
- max retries:
0
->2
- max retry delay (seconds)
2
->5
- max retries:
- Remove
StripeClient#connection_manager
. This was a legacy method from years ago. - Singleton
retrieve
method now requiresparams
to be passed as the first argument. Existing calls to singletonretrieve
method with onlyopts
argument will have to be updated to account for the addition ofparams
argument.params = { expand: ["available"] } opts = { stripe_account: "acct_123" } # ❌ No longer works Stripe::Balance.retrieve(opts) # ✅ Correct way to call retrieve method Stripe::Balance.retrieve(params, opts)
- Moved the
Stripe.raw_request()
method that was recently added toStripeClient
. This will use the configuration set on the StripeClient instead of the global configuration used before. - Remove
APIResource.request
. Instead, useStripeClient#raw_request
now.# Instead of Stripe::APIResource.request(:get, "/v1/endpoint", params, opts) # do client = Stripe::StripeClient.new(...) resp = client.raw_request(:get, "/v1/endpoint", params: params, opts: opts)
- Add an additional parameter to
APIResource.execute_resource_request
. However, we discourage use of this in favor ofStripeClient#raw_request
.APIResource.execute_resource_request(method, url, params = {}, opts = {}, usage = []) # is now, with base_address being one of [:api, :files, :connect, :meter_events] APIResource.execute_resource_request(method, url, base_address = :api, params = {}, opts = {}, usage = [])
- Change parameters to
APIRequestor.execute_request
(previouslyStripeClient.execute_request
). It now returns all request options from our internal request framework as the second value in the returned tuple, instead of only the API key used:# Before obj, api_key = StripeClient.new.execute_request(method, path, api_base: nil, api_key: nil, headers: {}, params: {}, usage: []) # is now, with base_address being one of [:api, :files, :connect, :meter_events] obj, opts = APIRequestor.new.execute_request(method, path, base_address, params: {}, opts: {}, usage: []) puts(opts) # will output {api_key: "sk_test_123", stripe_account: "acct_123"}
- Add support for new resources
Billing.CreditBalanceSummary
,Billing.CreditBalanceTransaction
,Billing.CreditGrant
, andMargin
- Add support for
retrieve
method on resourceCreditBalanceSummary
- Add support for
list
andretrieve
methods on resourceCreditBalanceTransaction
- Add support for
create
,expire
,list
,retrieve
,update
, andvoid_grant
methods on resourceCreditGrant