Square Connect Ruby SDK Technical Reference

August 15, 2019 ยท View on GitHub

The Square Connect Ruby SDK is retired (EOL) as of 2019-08-15 and will no longer receive bug fixes or product updates.

This SDK is automatically generated by the Swagger Codegen project:

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

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

Installation of Square Connect Ruby SDK

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

ClassMethodHTTP requestDescription
SquareConnect::ApplePayApiregister_domainPOST /v2/apple-pay/domainsRegisterDomain
SquareConnect::CatalogApibatch_delete_catalog_objectsPOST /v2/catalog/batch-deleteBatchDeleteCatalogObjects
SquareConnect::CatalogApibatch_retrieve_catalog_objectsPOST /v2/catalog/batch-retrieveBatchRetrieveCatalogObjects
SquareConnect::CatalogApibatch_upsert_catalog_objectsPOST /v2/catalog/batch-upsertBatchUpsertCatalogObjects
SquareConnect::CatalogApicatalog_infoGET /v2/catalog/infoCatalogInfo
SquareConnect::CatalogApidelete_catalog_objectDELETE /v2/catalog/object/{object_id}DeleteCatalogObject
SquareConnect::CatalogApilist_catalogGET /v2/catalog/listListCatalog
SquareConnect::CatalogApiretrieve_catalog_objectGET /v2/catalog/object/{object_id}RetrieveCatalogObject
SquareConnect::CatalogApisearch_catalog_objectsPOST /v2/catalog/searchSearchCatalogObjects
SquareConnect::CatalogApiupdate_item_modifier_listsPOST /v2/catalog/update-item-modifier-listsUpdateItemModifierLists
SquareConnect::CatalogApiupdate_item_taxesPOST /v2/catalog/update-item-taxesUpdateItemTaxes
SquareConnect::CatalogApiupsert_catalog_objectPOST /v2/catalog/objectUpsertCatalogObject
SquareConnect::CheckoutApicreate_checkoutPOST /v2/locations/{location_id}/checkoutsCreateCheckout
SquareConnect::CustomersApicreate_customerPOST /v2/customersCreateCustomer
SquareConnect::CustomersApicreate_customer_cardPOST /v2/customers/{customer_id}/cardsCreateCustomerCard
SquareConnect::CustomersApidelete_customerDELETE /v2/customers/{customer_id}DeleteCustomer
SquareConnect::CustomersApidelete_customer_cardDELETE /v2/customers/{customer_id}/cards/{card_id}DeleteCustomerCard
SquareConnect::CustomersApilist_customersGET /v2/customersListCustomers
SquareConnect::CustomersApiretrieve_customerGET /v2/customers/{customer_id}RetrieveCustomer
SquareConnect::CustomersApisearch_customersPOST /v2/customers/searchSearchCustomers
SquareConnect::CustomersApiupdate_customerPUT /v2/customers/{customer_id}UpdateCustomer
SquareConnect::EmployeesApilist_employeesGET /v2/employeesListEmployees
SquareConnect::EmployeesApiretrieve_employeeGET /v2/employees/{id}RetrieveEmployee
SquareConnect::InventoryApibatch_change_inventoryPOST /v2/inventory/batch-changeBatchChangeInventory
SquareConnect::InventoryApibatch_retrieve_inventory_changesPOST /v2/inventory/batch-retrieve-changesBatchRetrieveInventoryChanges
SquareConnect::InventoryApibatch_retrieve_inventory_countsPOST /v2/inventory/batch-retrieve-countsBatchRetrieveInventoryCounts
SquareConnect::InventoryApiretrieve_inventory_adjustmentGET /v2/inventory/adjustment/{adjustment_id}RetrieveInventoryAdjustment
SquareConnect::InventoryApiretrieve_inventory_changesGET /v2/inventory/{catalog_object_id}/changesRetrieveInventoryChanges
SquareConnect::InventoryApiretrieve_inventory_countGET /v2/inventory/{catalog_object_id}RetrieveInventoryCount
SquareConnect::InventoryApiretrieve_inventory_physical_countGET /v2/inventory/physical-count/{physical_count_id}RetrieveInventoryPhysicalCount
SquareConnect::LaborApicreate_break_typePOST /v2/labor/break-typesCreateBreakType
SquareConnect::LaborApicreate_shiftPOST /v2/labor/shiftsCreateShift
SquareConnect::LaborApidelete_break_typeDELETE /v2/labor/break-types/{id}DeleteBreakType
SquareConnect::LaborApidelete_shiftDELETE /v2/labor/shifts/{id}DeleteShift
SquareConnect::LaborApiget_break_typeGET /v2/labor/break-types/{id}GetBreakType
SquareConnect::LaborApiget_employee_wageGET /v2/labor/employee-wages/{id}GetEmployeeWage
SquareConnect::LaborApiget_shiftGET /v2/labor/shifts/{id}GetShift
SquareConnect::LaborApilist_break_typesGET /v2/labor/break-typesListBreakTypes
SquareConnect::LaborApilist_employee_wagesGET /v2/labor/employee-wagesListEmployeeWages
SquareConnect::LaborApilist_workweek_configsGET /v2/labor/workweek-configsListWorkweekConfigs
SquareConnect::LaborApisearch_shiftsPOST /v2/labor/shifts/searchSearchShifts
SquareConnect::LaborApiupdate_break_typePUT /v2/labor/break-types/{id}UpdateBreakType
SquareConnect::LaborApiupdate_shiftPUT /v2/labor/shifts/{id}UpdateShift
SquareConnect::LaborApiupdate_workweek_configPUT /v2/labor/workweek-configs/{id}UpdateWorkweekConfig
SquareConnect::LocationsApilist_locationsGET /v2/locationsListLocations
SquareConnect::MobileAuthorizationApicreate_mobile_authorization_codePOST /mobile/authorization-codeCreateMobileAuthorizationCode
SquareConnect::OAuthApiobtain_tokenPOST /oauth2/tokenObtainToken
SquareConnect::OAuthApirenew_tokenPOST /oauth2/clients/{client_id}/access-token/renewRenewToken
SquareConnect::OAuthApirevoke_tokenPOST /oauth2/revokeRevokeToken
SquareConnect::OrdersApibatch_retrieve_ordersPOST /v2/locations/{location_id}/orders/batch-retrieveBatchRetrieveOrders
SquareConnect::OrdersApicreate_orderPOST /v2/locations/{location_id}/ordersCreateOrder
SquareConnect::OrdersApisearch_ordersPOST /v2/orders/searchSearchOrders
SquareConnect::ReportingApilist_additional_recipient_receivable_refundsGET /v2/locations/{location_id}/additional-recipient-receivable-refundsListAdditionalRecipientReceivableRefunds
SquareConnect::ReportingApilist_additional_recipient_receivablesGET /v2/locations/{location_id}/additional-recipient-receivablesListAdditionalRecipientReceivables
SquareConnect::TransactionsApicapture_transactionPOST /v2/locations/{location_id}/transactions/{transaction_id}/captureCaptureTransaction
SquareConnect::TransactionsApichargePOST /v2/locations/{location_id}/transactionsCharge
SquareConnect::TransactionsApicreate_refundPOST /v2/locations/{location_id}/transactions/{transaction_id}/refundCreateRefund
SquareConnect::TransactionsApilist_refundsGET /v2/locations/{location_id}/refundsListRefunds
SquareConnect::TransactionsApilist_transactionsGET /v2/locations/{location_id}/transactionsListTransactions
SquareConnect::TransactionsApiretrieve_transactionGET /v2/locations/{location_id}/transactions/{transaction_id}RetrieveTransaction
SquareConnect::TransactionsApivoid_transactionPOST /v2/locations/{location_id}/transactions/{transaction_id}/voidVoidTransaction
SquareConnect::V1EmployeesApicreate_employeePOST /v1/me/employeesCreateEmployee
SquareConnect::V1EmployeesApicreate_employee_rolePOST /v1/me/rolesCreateEmployeeRole
SquareConnect::V1EmployeesApicreate_timecardPOST /v1/me/timecardsCreateTimecard
SquareConnect::V1EmployeesApidelete_timecardDELETE /v1/me/timecards/{timecard_id}DeleteTimecard
SquareConnect::V1EmployeesApilist_cash_drawer_shiftsGET /v1/{location_id}/cash-drawer-shiftsListCashDrawerShifts
SquareConnect::V1EmployeesApilist_employee_rolesGET /v1/me/rolesListEmployeeRoles
SquareConnect::V1EmployeesApilist_employeesGET /v1/me/employeesListEmployees
SquareConnect::V1EmployeesApilist_timecard_eventsGET /v1/me/timecards/{timecard_id}/eventsListTimecardEvents
SquareConnect::V1EmployeesApilist_timecardsGET /v1/me/timecardsListTimecards
SquareConnect::V1EmployeesApiretrieve_cash_drawer_shiftGET /v1/{location_id}/cash-drawer-shifts/{shift_id}RetrieveCashDrawerShift
SquareConnect::V1EmployeesApiretrieve_employeeGET /v1/me/employees/{employee_id}RetrieveEmployee
SquareConnect::V1EmployeesApiretrieve_employee_roleGET /v1/me/roles/{role_id}RetrieveEmployeeRole
SquareConnect::V1EmployeesApiretrieve_timecardGET /v1/me/timecards/{timecard_id}RetrieveTimecard
SquareConnect::V1EmployeesApiupdate_employeePUT /v1/me/employees/{employee_id}UpdateEmployee
SquareConnect::V1EmployeesApiupdate_employee_rolePUT /v1/me/roles/{role_id}UpdateEmployeeRole
SquareConnect::V1EmployeesApiupdate_timecardPUT /v1/me/timecards/{timecard_id}UpdateTimecard
SquareConnect::V1ItemsApiadjust_inventoryPOST /v1/{location_id}/inventory/{variation_id}AdjustInventory
SquareConnect::V1ItemsApiapply_feePUT /v1/{location_id}/items/{item_id}/fees/{fee_id}ApplyFee
SquareConnect::V1ItemsApiapply_modifier_listPUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}ApplyModifierList
SquareConnect::V1ItemsApicreate_categoryPOST /v1/{location_id}/categoriesCreateCategory
SquareConnect::V1ItemsApicreate_discountPOST /v1/{location_id}/discountsCreateDiscount
SquareConnect::V1ItemsApicreate_feePOST /v1/{location_id}/feesCreateFee
SquareConnect::V1ItemsApicreate_itemPOST /v1/{location_id}/itemsCreateItem
SquareConnect::V1ItemsApicreate_modifier_listPOST /v1/{location_id}/modifier-listsCreateModifierList
SquareConnect::V1ItemsApicreate_modifier_optionPOST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-optionsCreateModifierOption
SquareConnect::V1ItemsApicreate_pagePOST /v1/{location_id}/pagesCreatePage
SquareConnect::V1ItemsApicreate_variationPOST /v1/{location_id}/items/{item_id}/variationsCreateVariation
SquareConnect::V1ItemsApidelete_categoryDELETE /v1/{location_id}/categories/{category_id}DeleteCategory
SquareConnect::V1ItemsApidelete_discountDELETE /v1/{location_id}/discounts/{discount_id}DeleteDiscount
SquareConnect::V1ItemsApidelete_feeDELETE /v1/{location_id}/fees/{fee_id}DeleteFee
SquareConnect::V1ItemsApidelete_itemDELETE /v1/{location_id}/items/{item_id}DeleteItem
SquareConnect::V1ItemsApidelete_modifier_listDELETE /v1/{location_id}/modifier-lists/{modifier_list_id}DeleteModifierList
SquareConnect::V1ItemsApidelete_modifier_optionDELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}DeleteModifierOption
SquareConnect::V1ItemsApidelete_pageDELETE /v1/{location_id}/pages/{page_id}DeletePage
SquareConnect::V1ItemsApidelete_page_cellDELETE /v1/{location_id}/pages/{page_id}/cellsDeletePageCell
SquareConnect::V1ItemsApidelete_variationDELETE /v1/{location_id}/items/{item_id}/variations/{variation_id}DeleteVariation
SquareConnect::V1ItemsApilist_categoriesGET /v1/{location_id}/categoriesListCategories
SquareConnect::V1ItemsApilist_discountsGET /v1/{location_id}/discountsListDiscounts
SquareConnect::V1ItemsApilist_feesGET /v1/{location_id}/feesListFees
SquareConnect::V1ItemsApilist_inventoryGET /v1/{location_id}/inventoryListInventory
SquareConnect::V1ItemsApilist_itemsGET /v1/{location_id}/itemsListItems
SquareConnect::V1ItemsApilist_modifier_listsGET /v1/{location_id}/modifier-listsListModifierLists
SquareConnect::V1ItemsApilist_pagesGET /v1/{location_id}/pagesListPages
SquareConnect::V1ItemsApiremove_feeDELETE /v1/{location_id}/items/{item_id}/fees/{fee_id}RemoveFee
SquareConnect::V1ItemsApiremove_modifier_listDELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id}RemoveModifierList
SquareConnect::V1ItemsApiretrieve_itemGET /v1/{location_id}/items/{item_id}RetrieveItem
SquareConnect::V1ItemsApiretrieve_modifier_listGET /v1/{location_id}/modifier-lists/{modifier_list_id}RetrieveModifierList
SquareConnect::V1ItemsApiupdate_categoryPUT /v1/{location_id}/categories/{category_id}UpdateCategory
SquareConnect::V1ItemsApiupdate_discountPUT /v1/{location_id}/discounts/{discount_id}UpdateDiscount
SquareConnect::V1ItemsApiupdate_feePUT /v1/{location_id}/fees/{fee_id}UpdateFee
SquareConnect::V1ItemsApiupdate_itemPUT /v1/{location_id}/items/{item_id}UpdateItem
SquareConnect::V1ItemsApiupdate_modifier_listPUT /v1/{location_id}/modifier-lists/{modifier_list_id}UpdateModifierList
SquareConnect::V1ItemsApiupdate_modifier_optionPUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id}UpdateModifierOption
SquareConnect::V1ItemsApiupdate_pagePUT /v1/{location_id}/pages/{page_id}UpdatePage
SquareConnect::V1ItemsApiupdate_page_cellPUT /v1/{location_id}/pages/{page_id}/cellsUpdatePageCell
SquareConnect::V1ItemsApiupdate_variationPUT /v1/{location_id}/items/{item_id}/variations/{variation_id}UpdateVariation
SquareConnect::V1LocationsApilist_locationsGET /v1/me/locationsListLocations
SquareConnect::V1LocationsApiretrieve_businessGET /v1/meRetrieveBusiness
SquareConnect::V1TransactionsApicreate_refundPOST /v1/{location_id}/refundsCreateRefund
SquareConnect::V1TransactionsApilist_bank_accountsGET /v1/{location_id}/bank-accountsListBankAccounts
SquareConnect::V1TransactionsApilist_ordersGET /v1/{location_id}/ordersListOrders
SquareConnect::V1TransactionsApilist_paymentsGET /v1/{location_id}/paymentsListPayments
SquareConnect::V1TransactionsApilist_refundsGET /v1/{location_id}/refundsListRefunds
SquareConnect::V1TransactionsApilist_settlementsGET /v1/{location_id}/settlementsListSettlements
SquareConnect::V1TransactionsApiretrieve_bank_accountGET /v1/{location_id}/bank-accounts/{bank_account_id}RetrieveBankAccount
SquareConnect::V1TransactionsApiretrieve_orderGET /v1/{location_id}/orders/{order_id}RetrieveOrder
SquareConnect::V1TransactionsApiretrieve_paymentGET /v1/{location_id}/payments/{payment_id}RetrievePayment
SquareConnect::V1TransactionsApiretrieve_settlementGET /v1/{location_id}/settlements/{settlement_id}RetrieveSettlement
SquareConnect::V1TransactionsApiupdate_orderPUT /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 product catalog information. For example, to get an item or a list of items.
    • 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

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.