Ruby client library for the Square Connect APIs
Clone or download

README.md

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.20181212.0
  • Build package: io.swagger.codegen.languages.RubyClientCodegen

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

Installation

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'

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'

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::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::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::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 Creates an employee for a business.
SquareConnect::V1EmployeesApi create_employee_role POST /v1/me/roles Creates an employee role you can then assign to employees.
SquareConnect::V1EmployeesApi create_timecard POST /v1/me/timecards Creates a timecard for an employee. Each timecard corresponds to a single shift.
SquareConnect::V1EmployeesApi delete_timecard DELETE /v1/me/timecards/{timecard_id} Deletes a timecard. Deleted timecards are still accessible from Connect API endpoints, but the value of their deleted field is set to true. See Handling deleted timecards for more information.
SquareConnect::V1EmployeesApi list_cash_drawer_shifts GET /v1/{location_id}/cash-drawer-shifts Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days.
SquareConnect::V1EmployeesApi list_employee_roles GET /v1/me/roles Provides summary information for all of a business's employee roles.
SquareConnect::V1EmployeesApi list_employees GET /v1/me/employees Provides summary information for all of a business's employees.
SquareConnect::V1EmployeesApi list_timecard_events GET /v1/me/timecards/{timecard_id}/events Provides summary information for all events associated with a particular timecard.
SquareConnect::V1EmployeesApi list_timecards GET /v1/me/timecards Provides summary information for all of a business's employee timecards.
SquareConnect::V1EmployeesApi retrieve_cash_drawer_shift GET /v1/{location_id}/cash-drawer-shifts/{shift_id} Provides the details for a single cash drawer shift, including all events that occurred during the shift.
SquareConnect::V1EmployeesApi retrieve_employee GET /v1/me/employees/{employee_id} Provides the details for a single employee.
SquareConnect::V1EmployeesApi retrieve_employee_role GET /v1/me/roles/{role_id} Provides the details for a single employee role.
SquareConnect::V1EmployeesApi retrieve_timecard GET /v1/me/timecards/{timecard_id} Provides the details for a single timecard.
SquareConnect::V1EmployeesApi update_employee PUT /v1/me/employees/{employee_id} V1 UpdateEmployee
SquareConnect::V1EmployeesApi update_employee_role PUT /v1/me/roles/{role_id} Modifies the details of an employee role.
SquareConnect::V1EmployeesApi update_timecard PUT /v1/me/timecards/{timecard_id} Modifies a timecard's details. This creates an API_EDIT event for the timecard. You can view a timecard's event history with the List Timecard Events endpoint.
SquareConnect::V1ItemsApi adjust_inventory POST /v1/{location_id}/inventory/{variation_id} Adjusts an item variation's current available inventory.
SquareConnect::V1ItemsApi apply_fee PUT /v1/{location_id}/items/{item_id}/fees/{fee_id} Associates a fee with an item, meaning the fee is automatically applied to the item in Square Register.
SquareConnect::V1ItemsApi apply_modifier_list PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} Associates a modifier list with an item, meaning modifier options from the list can be applied to the item.
SquareConnect::V1ItemsApi create_category POST /v1/{location_id}/categories Creates an item category.
SquareConnect::V1ItemsApi create_discount POST /v1/{location_id}/discounts Creates a discount.
SquareConnect::V1ItemsApi create_fee POST /v1/{location_id}/fees Creates a fee (tax).
SquareConnect::V1ItemsApi create_item POST /v1/{location_id}/items Creates an item and at least one variation for it.
SquareConnect::V1ItemsApi create_modifier_list POST /v1/{location_id}/modifier-lists Creates an item modifier list and at least one modifier option for it.
SquareConnect::V1ItemsApi create_modifier_option POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options Creates an item modifier option and adds it to a modifier list.
SquareConnect::V1ItemsApi create_page POST /v1/{location_id}/pages Creates a Favorites page in Square Register.
SquareConnect::V1ItemsApi create_variation POST /v1/{location_id}/items/{item_id}/variations Creates an item variation for an existing item.
SquareConnect::V1ItemsApi delete_category DELETE /v1/{location_id}/categories/{category_id} Deletes an existing item category.
SquareConnect::V1ItemsApi delete_discount DELETE /v1/{location_id}/discounts/{discount_id} Deletes an existing discount.
SquareConnect::V1ItemsApi delete_fee DELETE /v1/{location_id}/fees/{fee_id} Deletes an existing fee (tax).
SquareConnect::V1ItemsApi delete_item DELETE /v1/{location_id}/items/{item_id} Deletes an existing item and all item variations associated with it.
SquareConnect::V1ItemsApi delete_modifier_list DELETE /v1/{location_id}/modifier-lists/{modifier_list_id} Deletes an existing item modifier list and all modifier options associated with it.
SquareConnect::V1ItemsApi delete_modifier_option DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} Deletes an existing item modifier option from a modifier list.
SquareConnect::V1ItemsApi delete_page DELETE /v1/{location_id}/pages/{page_id} Deletes an existing Favorites page and all of its cells.
SquareConnect::V1ItemsApi delete_page_cell DELETE /v1/{location_id}/pages/{page_id}/cells Deletes a cell from a Favorites page in Square Register.
SquareConnect::V1ItemsApi delete_variation DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id} Deletes an existing item variation from an item.
SquareConnect::V1ItemsApi list_categories GET /v1/{location_id}/categories Lists all of a location's item categories.
SquareConnect::V1ItemsApi list_discounts GET /v1/{location_id}/discounts Lists all of a location's discounts.
SquareConnect::V1ItemsApi list_fees GET /v1/{location_id}/fees Lists all of a location's fees (taxes).
SquareConnect::V1ItemsApi list_inventory GET /v1/{location_id}/inventory Provides inventory information for all of a merchant's inventory-enabled item variations.
SquareConnect::V1ItemsApi list_items GET /v1/{location_id}/items Provides summary information for all of a location's items.
SquareConnect::V1ItemsApi list_modifier_lists GET /v1/{location_id}/modifier-lists Lists all of a location's modifier lists.
SquareConnect::V1ItemsApi list_pages GET /v1/{location_id}/pages Lists all of a location's Favorites pages in Square Register.
SquareConnect::V1ItemsApi remove_fee DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id} Removes a fee assocation from an item, meaning the fee is no longer automatically applied to the item in Square Register.
SquareConnect::V1ItemsApi remove_modifier_list DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} Removes a modifier list association from an item, meaning modifier options from the list can no longer be applied to the item.
SquareConnect::V1ItemsApi retrieve_item GET /v1/{location_id}/items/{item_id} Provides the details for a single item, including associated modifier lists and fees.
SquareConnect::V1ItemsApi retrieve_modifier_list GET /v1/{location_id}/modifier-lists/{modifier_list_id} Provides the details for a single modifier list.
SquareConnect::V1ItemsApi update_category PUT /v1/{location_id}/categories/{category_id} Modifies the details of an existing item category.
SquareConnect::V1ItemsApi update_discount PUT /v1/{location_id}/discounts/{discount_id} Modifies the details of an existing discount.
SquareConnect::V1ItemsApi update_fee PUT /v1/{location_id}/fees/{fee_id} Modifies the details of an existing fee (tax).
SquareConnect::V1ItemsApi update_item PUT /v1/{location_id}/items/{item_id} Modifies the core details of an existing item.
SquareConnect::V1ItemsApi update_modifier_list PUT /v1/{location_id}/modifier-lists/{modifier_list_id} Modifies the details of an existing item modifier list.
SquareConnect::V1ItemsApi update_modifier_option PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} Modifies the details of an existing item modifier option.
SquareConnect::V1ItemsApi update_page PUT /v1/{location_id}/pages/{page_id} Modifies the details of a Favorites page in Square Register.
SquareConnect::V1ItemsApi update_page_cell PUT /v1/{location_id}/pages/{page_id}/cells Modifies a cell of a Favorites page in Square Register.
SquareConnect::V1ItemsApi update_variation PUT /v1/{location_id}/items/{item_id}/variations/{variation_id} Modifies the details of an existing item variation.
SquareConnect::V1LocationsApi list_locations GET /v1/me/locations Provides details for a business's locations, including their IDs.
SquareConnect::V1LocationsApi retrieve_business GET /v1/me Get a business's information.
SquareConnect::V1TransactionsApi create_refund POST /v1/{location_id}/refunds Issues a refund for a previously processed payment. You must issue a refund within 60 days of the associated payment.
SquareConnect::V1TransactionsApi list_bank_accounts GET /v1/{location_id}/bank-accounts Provides non-confidential details for all of a location's associated bank accounts. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.
SquareConnect::V1TransactionsApi list_orders GET /v1/{location_id}/orders Provides summary information for a merchant's online store orders.
SquareConnect::V1TransactionsApi list_payments GET /v1/{location_id}/payments Provides summary information for all payments taken by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. See Date ranges for details of inclusive and exclusive dates.
SquareConnect::V1TransactionsApi list_refunds GET /v1/{location_id}/refunds Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length.
SquareConnect::V1TransactionsApi list_settlements GET /v1/{location_id}/settlements Provides summary information for all deposits and withdrawals initiated by Square to a merchant's bank account during a date range. Date ranges cannot exceed one year in length.
SquareConnect::V1TransactionsApi retrieve_bank_account GET /v1/{location_id}/bank-accounts/{bank_account_id} Provides non-confidential details for a merchant's associated bank account. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.
SquareConnect::V1TransactionsApi retrieve_order GET /v1/{location_id}/orders/{order_id} Provides comprehensive information for a single online store order, including the order's history.
SquareConnect::V1TransactionsApi retrieve_payment GET /v1/{location_id}/payments/{payment_id} Provides comprehensive information for a single payment.
SquareConnect::V1TransactionsApi retrieve_settlement GET /v1/{location_id}/settlements/{settlement_id} Provides comprehensive information for a single settlement, including the entries that contribute to the settlement's total.
SquareConnect::V1TransactionsApi update_order PUT /v1/{location_id}/orders/{order_id} Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:

Documentation for Models

Documentation for Authorization

oauth2

  • Type: OAuth
  • Flow: accessCode
  • Authorization URL: https://connect.squareup.com/oauth2/authorize
  • Scopes:
    • MERCHANT_PROFILE_READ: GET endpoints related to a merchant's business and location entities. Almost all Connect API applications need this permission in order to obtain a merchant's location IDs
    • PAYMENTS_READ: GET endpoints related to transactions and refunds
    • PAYMENTS_WRITE: POST, PUT, and DELETE endpoints related to transactions and refunds. E-commerce applications must request this permission
    • CUSTOMERS_READ: GET endpoints related to customer management
    • CUSTOMERS_WRITE: POST, PUT, and DELETE endpoints related to customer management
    • SETTLEMENTS_READ: GET endpoints related to settlements (deposits)
    • BANK_ACCOUNTS_READ: GET endpoints related to a merchant's bank accounts
    • ITEMS_READ: GET endpoints related to a merchant's item library
    • ITEMS_WRITE: POST, PUT, and DELETE endpoints related to a merchant's item library
    • ORDERS_READ: GET endpoints related to a merchant's orders
    • ORDERS_WRITE: POST, PUT, and DELETE endpoints related to a merchant's orders
    • EMPLOYEES_READ: GET endpoints related to employee management
    • EMPLOYEES_WRITE: POST, PUT, and DELETE endpoints related to employee management
    • TIMECARDS_READ: GET endpoints related to employee timecards
    • TIMECARDS_WRITE: POST, PUT, and DELETE endpoints related to employee timecards
    • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: Allow third party applications to deduct a portion of each transaction amount.
    • PAYMENTS_WRITE_IN_PERSON: POST, PUT, and DELETE endpoints. Grants write access to transaction and refunds information.
    • INVENTORY_READ: GET endpoints related to a merchant's inventory
    • INVENTORY_WRITE: POST, PUT, and DELETE endpoints related to a merchant's inventory

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.