Migration guide for v13

StripeClient and service-based call pattern

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:

1. No global config: you can simultaneously use multiple clients with different configuration options (such as API keys)
2. 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.
3. No static methods results in easier mocking

How to upgrade

While there are no plans yet to completely remove the previous resource-based call pattern, it will be deprecated soon and new API endpoints will be supported only in the new pattern. We strongly recommend migrating to the new service-based pattern as you begin to use new APIs. This will help you avoid mixing the two patterns in your integration, which can lead to confusion as you maintain your code.

To migrate from a resource-based to service-based pattern:

1. 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. As of v13.3.1, for configurable options that are not specified or not currently available on StripeClient, we fall back to the global StripeConfiguration.

   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",
   )

2. 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 the v1 or v2 accessors.

   Before

   customer = Stripe::Customer.create({email: "[email protected]"}, {stripe_account: "acct_123"})

   After

   customer = client.v1.customers.create({email: "[email protected]"}, {stripe_account: "acct_123"})

3. Convert instance resource method calls to StripeClient calls.

   Before

   customer = Stripe::Customer.retrieve("cus_123");
   customer.delete();

   After

   client.v1.customers.delete("cus_123");

4. 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"},
   );

StripeClient#request

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

Changelog

• 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
• Remove StripeClient#connection_manager. This was a legacy method from years ago.
• Singleton retrieve method now requires params to be passed as the first argument. Existing calls to singleton retrieve method with only opts argument will have to be updated to account for the addition of params 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 to StripeClient. This will use the configuration set on the StripeClient instead of the global configuration used before.
• Remove APIResource.request. Instead, use StripeClient#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 of StripeClient#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 (previously StripeClient.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"}

Additions

• Add support for new resources Billing.CreditBalanceSummary, Billing.CreditBalanceTransaction, Billing.CreditGrant, and Margin
• Add support for retrieve method on resource CreditBalanceSummary
• Add support for list and retrieve methods on resource CreditBalanceTransaction
• Add support for create, expire, list, retrieve, update, and void_grant methods on resource CreditGrant