Square Connect Ruby SDKs Build StatusGem Version

If you have feedback about the new SDKs, or just want to talk to other Square Developers, request an invite to the new slack community for Square Developers

This repository contains the released Ruby client SDK. Check out our API specification repository for the specification and template files we used to generate this.

This SDK is automatically generated by the Swagger Codegen project:

  • API version: 2.0
  • Package version: 2.20190612.0
  • Build package: io.swagger.codegen.languages.RubyClientCodegen

For more information, please visit https://squareup.com/developers

Installation

Option1: RubyGems

The Ruby SDK is published as a gem. Simply run:

$ gem install square_connect

Or add this line to your Gemfile:

gem 'square_connect'

Option 2: Install from Git

If the Ruby gem is hosted at a git repository: https://github.com/square/connect-ruby-sdk, then add the following in the Gemfile:

gem 'square_connect', :git => 'https://github.com/square/connect-ruby-sdk.git'

Option 3: Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'square_connect'

# Setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

# The SDK throws an exception if a Connect endpoint responds with anything besides 200 (success).
# This block catches any exceptions that occur from the request.
locations_api = SquareConnect::LocationsApi.new
begin
  locations = locations_api.list_locations.locations
rescue SquareConnect::ApiError => e
  puts "Error encountered while loading the locations: #{e.message}"
end

Documentation for API Endpoints

All URIs are relative to https://connect.squareup.com

Class Method HTTP request Description
SquareConnect::ApplePayApi register_domain POST /v2/apple-pay/domains RegisterDomain
SquareConnect::CatalogApi batch_delete_catalog_objects POST /v2/catalog/batch-delete BatchDeleteCatalogObjects
SquareConnect::CatalogApi batch_retrieve_catalog_objects POST /v2/catalog/batch-retrieve BatchRetrieveCatalogObjects
SquareConnect::CatalogApi batch_upsert_catalog_objects POST /v2/catalog/batch-upsert BatchUpsertCatalogObjects
SquareConnect::CatalogApi catalog_info GET /v2/catalog/info CatalogInfo
SquareConnect::CatalogApi delete_catalog_object DELETE /v2/catalog/object/object_id DeleteCatalogObject
SquareConnect::CatalogApi list_catalog GET /v2/catalog/list ListCatalog
SquareConnect::CatalogApi retrieve_catalog_object GET /v2/catalog/object/object_id RetrieveCatalogObject
SquareConnect::CatalogApi search_catalog_objects POST /v2/catalog/search SearchCatalogObjects
SquareConnect::CatalogApi update_item_modifier_lists POST /v2/catalog/update-item-modifier-lists UpdateItemModifierLists
SquareConnect::CatalogApi update_item_taxes POST /v2/catalog/update-item-taxes UpdateItemTaxes
SquareConnect::CatalogApi upsert_catalog_object POST /v2/catalog/object UpsertCatalogObject
SquareConnect::CheckoutApi create_checkout POST /v2/locations/location_id/checkouts CreateCheckout
SquareConnect::CustomersApi create_customer POST /v2/customers CreateCustomer
SquareConnect::CustomersApi create_customer_card POST /v2/customers/customer_id/cards CreateCustomerCard
SquareConnect::CustomersApi delete_customer DELETE /v2/customers/customer_id DeleteCustomer
SquareConnect::CustomersApi delete_customer_card DELETE /v2/customers/customer_id/cards/card_id DeleteCustomerCard
SquareConnect::CustomersApi list_customers GET /v2/customers ListCustomers
SquareConnect::CustomersApi retrieve_customer GET /v2/customers/customer_id RetrieveCustomer
SquareConnect::CustomersApi search_customers POST /v2/customers/search SearchCustomers
SquareConnect::CustomersApi update_customer PUT /v2/customers/customer_id UpdateCustomer
SquareConnect::EmployeesApi list_employees GET /v2/employees ListEmployees
SquareConnect::EmployeesApi retrieve_employee GET /v2/employees/id RetrieveEmployee
SquareConnect::InventoryApi batch_change_inventory POST /v2/inventory/batch-change BatchChangeInventory
SquareConnect::InventoryApi batch_retrieve_inventory_changes POST /v2/inventory/batch-retrieve-changes BatchRetrieveInventoryChanges
SquareConnect::InventoryApi batch_retrieve_inventory_counts POST /v2/inventory/batch-retrieve-counts BatchRetrieveInventoryCounts
SquareConnect::InventoryApi retrieve_inventory_adjustment GET /v2/inventory/adjustment/adjustment_id RetrieveInventoryAdjustment
SquareConnect::InventoryApi retrieve_inventory_changes GET /v2/inventory/catalog_object_id/changes RetrieveInventoryChanges
SquareConnect::InventoryApi retrieve_inventory_count GET /v2/inventory/catalog_object_id RetrieveInventoryCount
SquareConnect::InventoryApi retrieve_inventory_physical_count GET /v2/inventory/physical-count/physical_count_id RetrieveInventoryPhysicalCount
SquareConnect::LaborApi create_break_type POST /v2/labor/break-types CreateBreakType
SquareConnect::LaborApi create_shift POST /v2/labor/shifts CreateShift
SquareConnect::LaborApi delete_break_type DELETE /v2/labor/break-types/id DeleteBreakType
SquareConnect::LaborApi delete_shift DELETE /v2/labor/shifts/id DeleteShift
SquareConnect::LaborApi get_break_type GET /v2/labor/break-types/id GetBreakType
SquareConnect::LaborApi get_employee_wage GET /v2/labor/employee-wages/id GetEmployeeWage
SquareConnect::LaborApi get_shift GET /v2/labor/shifts/id GetShift
SquareConnect::LaborApi list_break_types GET /v2/labor/break-types ListBreakTypes
SquareConnect::LaborApi list_employee_wages GET /v2/labor/employee-wages ListEmployeeWages
SquareConnect::LaborApi list_workweek_configs GET /v2/labor/workweek-configs ListWorkweekConfigs
SquareConnect::LaborApi search_shifts POST /v2/labor/shifts/search SearchShifts
SquareConnect::LaborApi update_break_type PUT /v2/labor/break-types/id UpdateBreakType
SquareConnect::LaborApi update_shift PUT /v2/labor/shifts/id UpdateShift
SquareConnect::LaborApi update_workweek_config PUT /v2/labor/workweek-configs/id UpdateWorkweekConfig
SquareConnect::LocationsApi list_locations GET /v2/locations ListLocations
SquareConnect::MobileAuthorizationApi create_mobile_authorization_code POST /mobile/authorization-code CreateMobileAuthorizationCode
SquareConnect::OAuthApi obtain_token POST /oauth2/token ObtainToken
SquareConnect::OAuthApi renew_token POST /oauth2/clients/client_id/access-token/renew RenewToken
SquareConnect::OAuthApi revoke_token POST /oauth2/revoke RevokeToken
SquareConnect::OrdersApi batch_retrieve_orders POST /v2/locations/location_id/orders/batch-retrieve BatchRetrieveOrders
SquareConnect::OrdersApi create_order POST /v2/locations/location_id/orders CreateOrder
SquareConnect::OrdersApi search_orders POST /v2/orders/search SearchOrders
SquareConnect::ReportingApi list_additional_recipient_receivable_refunds GET /v2/locations/location_id/additional-recipient-receivable-refunds ListAdditionalRecipientReceivableRefunds
SquareConnect::ReportingApi list_additional_recipient_receivables GET /v2/locations/location_id/additional-recipient-receivables ListAdditionalRecipientReceivables
SquareConnect::TransactionsApi capture_transaction POST /v2/locations/location_id/transactions/transaction_id/capture CaptureTransaction
SquareConnect::TransactionsApi charge POST /v2/locations/location_id/transactions Charge
SquareConnect::TransactionsApi create_refund POST /v2/locations/location_id/transactions/transaction_id/refund CreateRefund
SquareConnect::TransactionsApi list_refunds GET /v2/locations/location_id/refunds ListRefunds
SquareConnect::TransactionsApi list_transactions GET /v2/locations/location_id/transactions ListTransactions
SquareConnect::TransactionsApi retrieve_transaction GET /v2/locations/location_id/transactions/transaction_id RetrieveTransaction
SquareConnect::TransactionsApi void_transaction POST /v2/locations/location_id/transactions/transaction_id/void VoidTransaction
SquareConnect::V1EmployeesApi create_employee POST /v1/me/employees CreateEmployee
SquareConnect::V1EmployeesApi create_employee_role POST /v1/me/roles CreateEmployeeRole
SquareConnect::V1EmployeesApi create_timecard POST /v1/me/timecards CreateTimecard
SquareConnect::V1EmployeesApi delete_timecard DELETE /v1/me/timecards/timecard_id DeleteTimecard
SquareConnect::V1EmployeesApi list_cash_drawer_shifts GET /v1/location_id/cash-drawer-shifts ListCashDrawerShifts
SquareConnect::V1EmployeesApi list_employee_roles GET /v1/me/roles ListEmployeeRoles
SquareConnect::V1EmployeesApi list_employees GET /v1/me/employees ListEmployees
SquareConnect::V1EmployeesApi list_timecard_events GET /v1/me/timecards/timecard_id/events ListTimecardEvents
SquareConnect::V1EmployeesApi list_timecards GET /v1/me/timecards ListTimecards
SquareConnect::V1EmployeesApi retrieve_cash_drawer_shift GET /v1/location_id/cash-drawer-shifts/shift_id RetrieveCashDrawerShift
SquareConnect::V1EmployeesApi retrieve_employee GET /v1/me/employees/employee_id RetrieveEmployee
SquareConnect::V1EmployeesApi retrieve_employee_role GET /v1/me/roles/role_id RetrieveEmployeeRole
SquareConnect::V1EmployeesApi retrieve_timecard GET /v1/me/timecards/timecard_id RetrieveTimecard
SquareConnect::V1EmployeesApi update_employee PUT /v1/me/employees/employee_id UpdateEmployee
SquareConnect::V1EmployeesApi update_employee_role PUT /v1/me/roles/role_id UpdateEmployeeRole
SquareConnect::V1EmployeesApi update_timecard PUT /v1/me/timecards/timecard_id UpdateTimecard
SquareConnect::V1ItemsApi adjust_inventory POST /v1/location_id/inventory/variation_id AdjustInventory
SquareConnect::V1ItemsApi apply_fee PUT /v1/location_id/items/item_id/fees/fee_id ApplyFee
SquareConnect::V1ItemsApi apply_modifier_list PUT /v1/location_id/items/item_id/modifier-lists/modifier_list_id ApplyModifierList
SquareConnect::V1ItemsApi create_category POST /v1/location_id/categories CreateCategory
SquareConnect::V1ItemsApi create_discount POST /v1/location_id/discounts CreateDiscount
SquareConnect::V1ItemsApi create_fee POST /v1/location_id/fees CreateFee
SquareConnect::V1ItemsApi create_item POST /v1/location_id/items CreateItem
SquareConnect::V1ItemsApi create_modifier_list POST /v1/location_id/modifier-lists CreateModifierList
SquareConnect::V1ItemsApi create_modifier_option POST /v1/location_id/modifier-lists/modifier_list_id/modifier-options CreateModifierOption
SquareConnect::V1ItemsApi create_page POST /v1/location_id/pages CreatePage
SquareConnect::V1ItemsApi create_variation POST /v1/location_id/items/item_id/variations CreateVariation
SquareConnect::V1ItemsApi delete_category DELETE /v1/location_id/categories/category_id DeleteCategory
SquareConnect::V1ItemsApi delete_discount DELETE /v1/location_id/discounts/discount_id DeleteDiscount
SquareConnect::V1ItemsApi delete_fee DELETE /v1/location_id/fees/fee_id DeleteFee
SquareConnect::V1ItemsApi delete_item DELETE /v1/location_id/items/item_id DeleteItem
SquareConnect::V1ItemsApi delete_modifier_list DELETE /v1/location_id/modifier-lists/modifier_list_id DeleteModifierList
SquareConnect::V1ItemsApi delete_modifier_option DELETE /v1/location_id/modifier-lists/modifier_list_id/modifier-options/modifier_option_id DeleteModifierOption
SquareConnect::V1ItemsApi delete_page DELETE /v1/location_id/pages/page_id DeletePage
SquareConnect::V1ItemsApi delete_page_cell DELETE /v1/location_id/pages/page_id/cells DeletePageCell
SquareConnect::V1ItemsApi delete_variation DELETE /v1/location_id/items/item_id/variations/variation_id DeleteVariation
SquareConnect::V1ItemsApi list_categories GET /v1/location_id/categories ListCategories
SquareConnect::V1ItemsApi list_discounts GET /v1/location_id/discounts ListDiscounts
SquareConnect::V1ItemsApi list_fees GET /v1/location_id/fees ListFees
SquareConnect::V1ItemsApi list_inventory GET /v1/location_id/inventory ListInventory
SquareConnect::V1ItemsApi list_items GET /v1/location_id/items ListItems
SquareConnect::V1ItemsApi list_modifier_lists GET /v1/location_id/modifier-lists ListModifierLists
SquareConnect::V1ItemsApi list_pages GET /v1/location_id/pages ListPages
SquareConnect::V1ItemsApi remove_fee DELETE /v1/location_id/items/item_id/fees/fee_id RemoveFee
SquareConnect::V1ItemsApi remove_modifier_list DELETE /v1/location_id/items/item_id/modifier-lists/modifier_list_id RemoveModifierList
SquareConnect::V1ItemsApi retrieve_item GET /v1/location_id/items/item_id RetrieveItem
SquareConnect::V1ItemsApi retrieve_modifier_list GET /v1/location_id/modifier-lists/modifier_list_id RetrieveModifierList
SquareConnect::V1ItemsApi update_category PUT /v1/location_id/categories/category_id UpdateCategory
SquareConnect::V1ItemsApi update_discount PUT /v1/location_id/discounts/discount_id UpdateDiscount
SquareConnect::V1ItemsApi update_fee PUT /v1/location_id/fees/fee_id UpdateFee
SquareConnect::V1ItemsApi update_item PUT /v1/location_id/items/item_id UpdateItem
SquareConnect::V1ItemsApi update_modifier_list PUT /v1/location_id/modifier-lists/modifier_list_id UpdateModifierList
SquareConnect::V1ItemsApi update_modifier_option PUT /v1/location_id/modifier-lists/modifier_list_id/modifier-options/modifier_option_id UpdateModifierOption
SquareConnect::V1ItemsApi update_page PUT /v1/location_id/pages/page_id UpdatePage
SquareConnect::V1ItemsApi update_page_cell PUT /v1/location_id/pages/page_id/cells UpdatePageCell
SquareConnect::V1ItemsApi update_variation PUT /v1/location_id/items/item_id/variations/variation_id UpdateVariation
SquareConnect::V1LocationsApi list_locations GET /v1/me/locations ListLocations
SquareConnect::V1LocationsApi retrieve_business GET /v1/me RetrieveBusiness
SquareConnect::V1TransactionsApi create_refund POST /v1/location_id/refunds CreateRefund
SquareConnect::V1TransactionsApi list_bank_accounts GET /v1/location_id/bank-accounts ListBankAccounts
SquareConnect::V1TransactionsApi list_orders GET /v1/location_id/orders ListOrders
SquareConnect::V1TransactionsApi list_payments GET /v1/location_id/payments ListPayments
SquareConnect::V1TransactionsApi list_refunds GET /v1/location_id/refunds ListRefunds
SquareConnect::V1TransactionsApi list_settlements GET /v1/location_id/settlements ListSettlements
SquareConnect::V1TransactionsApi retrieve_bank_account GET /v1/location_id/bank-accounts/bank_account_id RetrieveBankAccount
SquareConnect::V1TransactionsApi retrieve_order GET /v1/location_id/orders/order_id RetrieveOrder
SquareConnect::V1TransactionsApi retrieve_payment GET /v1/location_id/payments/payment_id RetrievePayment
SquareConnect::V1TransactionsApi retrieve_settlement GET /v1/location_id/settlements/settlement_id RetrieveSettlement
SquareConnect::V1TransactionsApi update_order PUT /v1/location_id/orders/order_id UpdateOrder

Documentation for Models

Documentation for Authorization

oauth2

  • Type: OAuth
  • Flow: accessCode
  • Authorization URL: https://connect.squareup.com/oauth2/authorize
  • Scopes:
    • BANK_ACCOUNTS_READ: HTTP Method: `GET` Grants read access to bank account information associated with the targeted Square account. For example, to call the Connect v1 ListBankAccounts endpoint.
    • CUSTOMERS_READ: HTTP Method: `GET` Grants read access to customer information. For example, to call the ListCustomers endpoint.
    • CUSTOMERS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to customer information. For example, to create and update customer profiles.
    • EMPLOYEES_READ: HTTP Method: `GET` Grants read access to employee profile information. For example, to call the Connect v1 Employees API.
    • EMPLOYEES_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee profile information. For example, to create and modify employee profiles.
    • INVENTORY_READ: HTTP Method: `GET` Grants read access to inventory information. For example, to call the RetrieveInventoryCount endpoint.
    • INVENTORY_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to inventory information. For example, to call the BatchChangeInventory endpoint.
    • ITEMS_READ: HTTP Method: `GET` Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.
    • ITEMS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to product catalog information. For example, to modify or add to a product catalog.
    • MERCHANT_PROFILE_READ: HTTP Method: `GET` Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.
    • ORDERS_READ: HTTP Method: `GET` Grants read access to order information. For example, to call the BatchRetrieveOrders endpoint.
    • ORDERS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to order information. For example, to call the CreateCheckout endpoint.
    • PAYMENTS_READ: HTTP Method: `GET` Grants read access to transaction and refund information. For example, to call the RetrieveTransaction endpoint.
    • PAYMENTS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to transaction and refunds information. For example, to process payments with the Transactions or Checkout API.
    • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: HTTP Method: `POST`, `PUT`, `DELETE` Allow third party applications to deduct a portion of each transaction amount. Required to use multiparty transaction functionality with the Transactions API.
    • PAYMENTS_WRITE_IN_PERSON: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to transaction and refunds information. For example, to process in-person payments.
    • SETTLEMENTS_READ: HTTP Method: `GET` Grants read access to settlement (deposit) information. For example, to call the Connect v1 ListSettlements endpoint.
    • TIMECARDS_READ: HTTP Method: `GET` Grants read access to employee timecard information. For example, to call the Connect v1 ListTimecards endpoint.
    • TIMECARDS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee timecard information. For example, to create and modify timecards.
    • TIMECARDS_SETTINGS_READ: HTTP Method: `GET` Grants read access to employee timecard settings information. For example, to call the GetBreakType endpoint.
    • TIMECARDS_SETTINGS_WRITE: HTTP Method: `POST`, `PUT`, `DELETE` Grants write access to employee timecard settings information. For example, to call the UpdateBreakType endpoint.

oauth2ClientSecret

  • Type: API key
  • API key parameter name: Authorization
  • Location: HTTP header

Pagination of V1 Endpoints

V1 Endpoints return pagination information via HTTP headers. In order to obtain response headers and extract the batch_token parameter you will need to follow the following steps:

  1. Use the full information endpoint methods of each API to get the response HTTP Headers. They are named as their simple counterpart with a with_http_info suffix. Hence listEmployeeRoles would be called list_employee_roles_with_http_info. This method returns an array with 3 parameters: response, http_status, and http_headers.
  2. Use batch_token = api_client.get_v1_batch_token_from_headers(http_headers) to extract the token and proceed to get the following page if a token is present.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::V1EmployeesApi.new
api_client = api_instance.api_client

opts = {
  order: "order_example", # String | The order in which employees are listed in the response, based on their created_at field.Default value: ASC
  limit: 56 # Integer | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
}

roles = []
begin
  result, status, headers = api_instance.list_employee_roles_with_http_info(opts)
  roles = roles + result
  opts[:batch_token] = api_client.get_v1_batch_token_from_headers(headers)
rescue SquareConnect::ApiError => e
  puts "Exception when calling V1EmployeesApi#list_employee_roles_with_http_info: #{e}"
end while opts[:batch_token]

p roles

Contributing

Send bug reports, feature requests, and code contributions to the API specifications repository, as this repository contains only the generated SDK code.

License

Copyright 2017 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.