Announcing Square’s New Ruby SDK

We're excited to announce square.rb, our new Ruby SDK gem. You can use square.rb to integrate Square payments into your app. Run your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, Orders, and more.

To install the gem, just gem install square.rb from the command line or add gem: 'square.rb' to your Gemfile. Next, all you need to do is provide your access token and you're ready to use Square APIs.

require 'square'

square = Square::Client.new access_token: 'YOUR_ACCESS_TOKEN'
response = square.employees.list_employees

response.data.employees.first
#=> {:id=>"3WHf2i_KwYIaoKsw3AMv", ...

One of the great features in the new gem is that the response object contains new rich information about both the request and response. These details can be used for control flow and debugging.

Below are examples of checking the basic response status.

response.success?
#=> true

response.error?
#=> false

response.errors
#=> []

response.reason_phrase
#=> "OK"

response.status_code
#=> 200

You can also easily dig in further to get the raw JSON body, as well as headers for both the request and response, and much more.

response.raw_body
#=> "{\"customers\":[{\"id\":\"...

response.headers
#=> {"content-type"=>"application/json", …

response.request.headers
#=> {"accept"=>"application/json", …

response.request.query_url
#=> "https://connect.squareup.com/v2/customers"

response.request.parameters
#=> {}

While the response exposes a lot of information, you can always get the data payload with the #data method.

response.data.to_h
#=> {:customers=>[{:id=>"5ETRS70GPRZ9KC6W52W445BNN8", ...

If you were previously using the square_connect gem, you might be wondering how square.rb compares. Let's take a look! For example, let's create the following customer along with their address:

new_customer = {
 given_name: 'Ava',
 address: {
   address_line_1: '500 Electric Ave',
   locality: 'New York',
   country: 'US'
 }
}

First, let's look at how we used to create a customer with the legacy square_connect gem:

require 'square_connect'

SquareConnect.configure do |config|
 config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CustomersApi.new

address = SquareConnect::Address.new(new_customer[:address])

body = SquareConnect::CreateCustomerRequest.new(
 given_name: new_customer[:given_name],
 address: address
)

begin
 response = api_instance.create_customer(body)
 p response.customer.to_hash
rescue SquareConnect::ApiError
 warn response.errors
end

For comparison, let's create the same customer with the new square.rb gem:

require 'square'

square = Square::Client.new(access_token: 'YOUR ACCESS TOKEN')

response = square.customers.create_customer(body: new_customer)

if response.success?
 p response.data
else
 warn response.errors
end

That's all there is to it!

As you can see, the new square.rb gem interface is much simpler, less verbose, and uses plain old Ruby objects (POROs) instead of custom models. The new gem also ships with a ton of usability and debugging features.

Give the square.rb beta gem a try today by installing it with gem install square.rb.

With the new square.rb gem it's easier than ever to use Square as a platform to run your business with Ruby. We can't wait to see what you'll build! If you have any questions or feedback, drop by our developer community. We'd love to hear from you. You can check out the SDK over at https://github.com/square/square-ruby-sdk