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 = SquareLegacy::Client.new(
  bearer_auth_credentials: SquareLegacy::BearerAuthCredentials.new(
    access_token: ENV.fetch('SQUARE_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 square.rb gem also ships the legacy SDK under the square_legacy name, so the two 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 = SquareLegacy::Client.new(
  bearer_auth_credentials: SquareLegacy::BearerAuthCredentials.new(
    access_token: ENV.fetch('SQUARE_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 by running gem install square.rb.
2. Search and replace all requires from square to square_legacy.
3. 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 = legacy_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(
  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'
  }
)

Note that the legacy client wrapped request fields in a body: hash. The new client takes request fields directly as keyword arguments, so there is no body: wrapper. Beyond that, 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 = legacy_client.customers.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 Square::Errors::ApiError class. Rescue Square::Errors::ResponseError to handle any non-2xx response.

# NEW
begin
  result = client.customers.create(given_name: 'John')
rescue Square::Errors::ResponseError => e
  puts e.code
  puts e.message
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 new client returns an iterator that includes Enumerable, so iterate it with each:

# NEW
customers = client.customers.list(
  limit: 10,
  sort_field: 'DEFAULT',
  sort_order: 'DESC'
)

customers.each do |customer|
  puts customer.id
end