Ruby SDK Migration Guide

Version 44.0.0.20250820 of the Ruby SDK represents a full rewrite of the SDK, with a number of breaking changes, outlined in the following sections. When upgrading to this version or later versions, take note of the changes in the SDK, including client construction and parameter names. If necessary, you can use the legacy version of the SDK along with the latest version.

SDK versions 43.0.1.20250716 and earlier continue to function as expected, but you should plan to update your integration as soon as possible to ensure continued support.

The new version of the Ruby SDK introduces breaking changes in the client class.

// LEGACY
require 'square_legacy'

client = Square::LegacyClient.new(
  bearer_auth_credentials: BearerAuthCredentials.new(
    access_token: ENV['SQUARE_ACCESS_TOKEN']
  ),
  environment: 'sandbox'
)

// NEW
require 'square'

client = Square::Client.new(
  base_url: Square::Environment::PRODUCTION,
  token: 'YOUR_API_KEY'
)

While the new SDK has many improvements, it takes time to upgrade when there are breaking changes. To make the migration easier, the old SDK is published as square_legacy so that the two SDKs can be used side by side in the same project.

The following example shows how to use the new and legacy SDKs inside a single file:

require 'square'
require 'square_legacy'

client = Square::Client.new(token: 'YOUR_API_KEY')

legacy_client = Square::LegacyClient.new(
  bearer_auth_credentials: BearerAuthCredentials.new(
    access_token: ENV['SQUARE_ACCESS_TOKEN']
  ),
)

# List all payments with the new client.
new_response = client.payments.list()

# List all payments with the legacy client.
legacy_response = legacy_client.payments.list_payments()

You should migrate to the new SDK using the following steps:

1. Upgrade the gem to ^44.0.0.
2. Run gem install square.rb.
3. Search and replace all requires from square to square_legacy.
4. Gradually move over to use the new SDK by importing it from the square module.

The previous version of the SDK had no strong typing, so users had to craft payloads without any help from autocomplete. The newly generated SDK comes with YARD documentation and RBS types so that developers can let their IDE guide them.

// LEGACY
result = client.customers.create_customer(body: {
  "given_name": "John",
  "family_name": "Smith",
  "address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "locality": "New York",
    "administrative_district_level_1": "NY",
    "postal_code": "98100",
    "country": "US"
  }
})

// NEW
result = client.customers.create(body: {
  "given_name": "John",
  "family_name": "Smith",
  "address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "locality": "New York",
    "administrative_district_level_1": "NY",
    "postal_code": "98100",
    "country": "US"
  }
})

While the before and after code snippets remain similar, the experience of writing in an editor is quite different.

The legacy SDK represents successful calls and errors with the same ApiResponse type. Users could distinguish between successes and errors as shown:

// LEGACY
result = customers_api.create_customer(body: body)

if result.success?
  puts result.data
elsif result.error?
  warn result.errors
end

The new SDK represents errors as Exceptions, all of which inherit from the SquareError class.

begin
  result = customers_api.create_customer(body: body)
rescue Square::SquareError => e
  puts("The server could not be reached")
  puts(e.cause)
end

Square's paginated endpoints now support auto-pagination with an iterator. Callers don't need to manually fetch the next page. You can now iterate over the entire list and the client automatically fetches the next page behind the scenes.

The following example shows the same code, with the legacy and new SDKs:

page = client.customers.list(
  body: {
    limit: 10,
    sort_field: 'DEFAULT',
    sort_order: 'DESC'
  }
)

page.auto_paging_each do |customer|
    puts(customer.id)