Skip to content
Javascript client library for the Square Connect APIs https://docs.connect.squareup.com/
JavaScript
Branch: master
Clone or download
Latest commit d3e1f9d Aug 16, 2019

README.md

Square logo

Square Connect Node SDK


Build Status npm version Apache-2 license

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

Requirements

Node.js 6.0 or later

Installation

For Node.js

To install the SDK:

npm install square-connect --save

Getting Started

Please follow the installation instruction and execute the following JS code:

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = "YOUR ACCESS TOKEN";

var api = new SquareConnect.LocationsApi();

api.listLocations().then(function(data) {
  console.log('API called successfully. Returned data: ' + JSON.stringify(data, 0, 1));
}, function(error) {
  console.error(error);
});

How to configure sandbox environment

var SquareConnect = require('square-connect');
var client = SquareConnect.ApiClient.instance;
// Set sandbox url
client.basePath = 'https://connect.squareupsandbox.com';
// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
// Set sandbox access token
oauth2.accessToken = "YOUR SANDBOX ACCESS TOKEN";
// Pass client to API
var api = new SquareConnect.LocationsApi();

Documentation for API Endpoints

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

Class Method HTTP request Description
SquareConnect.ApplePayApi registerDomain POST /v2/apple-pay/domains RegisterDomain
SquareConnect.CatalogApi batchDeleteCatalogObjects POST /v2/catalog/batch-delete BatchDeleteCatalogObjects
SquareConnect.CatalogApi batchRetrieveCatalogObjects POST /v2/catalog/batch-retrieve BatchRetrieveCatalogObjects
SquareConnect.CatalogApi batchUpsertCatalogObjects POST /v2/catalog/batch-upsert BatchUpsertCatalogObjects
SquareConnect.CatalogApi catalogInfo GET /v2/catalog/info CatalogInfo
SquareConnect.CatalogApi deleteCatalogObject DELETE /v2/catalog/object/{object_id} DeleteCatalogObject
SquareConnect.CatalogApi listCatalog GET /v2/catalog/list ListCatalog
SquareConnect.CatalogApi retrieveCatalogObject GET /v2/catalog/object/{object_id} RetrieveCatalogObject
SquareConnect.CatalogApi searchCatalogObjects POST /v2/catalog/search SearchCatalogObjects
SquareConnect.CatalogApi updateItemModifierLists POST /v2/catalog/update-item-modifier-lists UpdateItemModifierLists
SquareConnect.CatalogApi updateItemTaxes POST /v2/catalog/update-item-taxes UpdateItemTaxes
SquareConnect.CatalogApi upsertCatalogObject POST /v2/catalog/object UpsertCatalogObject
SquareConnect.CheckoutApi createCheckout POST /v2/locations/{location_id}/checkouts CreateCheckout
SquareConnect.CustomersApi createCustomer POST /v2/customers CreateCustomer
SquareConnect.CustomersApi createCustomerCard POST /v2/customers/{customer_id}/cards CreateCustomerCard
SquareConnect.CustomersApi deleteCustomer DELETE /v2/customers/{customer_id} DeleteCustomer
SquareConnect.CustomersApi deleteCustomerCard DELETE /v2/customers/{customer_id}/cards/{card_id} DeleteCustomerCard
SquareConnect.CustomersApi listCustomers GET /v2/customers ListCustomers
SquareConnect.CustomersApi retrieveCustomer GET /v2/customers/{customer_id} RetrieveCustomer
SquareConnect.CustomersApi searchCustomers POST /v2/customers/search SearchCustomers
SquareConnect.CustomersApi updateCustomer PUT /v2/customers/{customer_id} UpdateCustomer
SquareConnect.EmployeesApi listEmployees GET /v2/employees ListEmployees
SquareConnect.EmployeesApi retrieveEmployee GET /v2/employees/{id} RetrieveEmployee
SquareConnect.InventoryApi batchChangeInventory POST /v2/inventory/batch-change BatchChangeInventory
SquareConnect.InventoryApi batchRetrieveInventoryChanges POST /v2/inventory/batch-retrieve-changes BatchRetrieveInventoryChanges
SquareConnect.InventoryApi batchRetrieveInventoryCounts POST /v2/inventory/batch-retrieve-counts BatchRetrieveInventoryCounts
SquareConnect.InventoryApi retrieveInventoryAdjustment GET /v2/inventory/adjustment/{adjustment_id} RetrieveInventoryAdjustment
SquareConnect.InventoryApi retrieveInventoryChanges GET /v2/inventory/{catalog_object_id}/changes RetrieveInventoryChanges
SquareConnect.InventoryApi retrieveInventoryCount GET /v2/inventory/{catalog_object_id} RetrieveInventoryCount
SquareConnect.InventoryApi retrieveInventoryPhysicalCount GET /v2/inventory/physical-count/{physical_count_id} RetrieveInventoryPhysicalCount
SquareConnect.LaborApi createBreakType POST /v2/labor/break-types CreateBreakType
SquareConnect.LaborApi createShift POST /v2/labor/shifts CreateShift
SquareConnect.LaborApi deleteBreakType DELETE /v2/labor/break-types/{id} DeleteBreakType
SquareConnect.LaborApi deleteShift DELETE /v2/labor/shifts/{id} DeleteShift
SquareConnect.LaborApi getBreakType GET /v2/labor/break-types/{id} GetBreakType
SquareConnect.LaborApi getEmployeeWage GET /v2/labor/employee-wages/{id} GetEmployeeWage
SquareConnect.LaborApi getShift GET /v2/labor/shifts/{id} GetShift
SquareConnect.LaborApi listBreakTypes GET /v2/labor/break-types ListBreakTypes
SquareConnect.LaborApi listEmployeeWages GET /v2/labor/employee-wages ListEmployeeWages
SquareConnect.LaborApi listWorkweekConfigs GET /v2/labor/workweek-configs ListWorkweekConfigs
SquareConnect.LaborApi searchShifts POST /v2/labor/shifts/search SearchShifts
SquareConnect.LaborApi updateBreakType PUT /v2/labor/break-types/{id} UpdateBreakType
SquareConnect.LaborApi updateShift PUT /v2/labor/shifts/{id} UpdateShift
SquareConnect.LaborApi updateWorkweekConfig PUT /v2/labor/workweek-configs/{id} UpdateWorkweekConfig
SquareConnect.LocationsApi listLocations GET /v2/locations ListLocations
SquareConnect.MobileAuthorizationApi createMobileAuthorizationCode POST /mobile/authorization-code CreateMobileAuthorizationCode
SquareConnect.OAuthApi obtainToken POST /oauth2/token ObtainToken
SquareConnect.OAuthApi renewToken POST /oauth2/clients/{client_id}/access-token/renew RenewToken
SquareConnect.OAuthApi revokeToken POST /oauth2/revoke RevokeToken
SquareConnect.OrdersApi batchRetrieveOrders POST /v2/locations/{location_id}/orders/batch-retrieve BatchRetrieveOrders
SquareConnect.OrdersApi createOrder POST /v2/locations/{location_id}/orders CreateOrder
SquareConnect.OrdersApi payOrder POST /v2/orders/{order_id}/pay PayOrder
SquareConnect.OrdersApi searchOrders POST /v2/orders/search SearchOrders
SquareConnect.OrdersApi updateOrder PUT /v2/locations/{location_id}/orders/{order_id} UpdateOrder
SquareConnect.PaymentsApi cancelPayment POST /v2/payments/{payment_id}/cancel CancelPayment
SquareConnect.PaymentsApi cancelPaymentByIdempotencyKey POST /v2/payments/cancel CancelPaymentByIdempotencyKey
SquareConnect.PaymentsApi completePayment POST /v2/payments/{payment_id}/complete CompletePayment
SquareConnect.PaymentsApi createPayment POST /v2/payments CreatePayment
SquareConnect.PaymentsApi getPayment GET /v2/payments/{payment_id} GetPayment
SquareConnect.PaymentsApi listPayments GET /v2/payments ListPayments
SquareConnect.RefundsApi getPaymentRefund GET /v2/refunds/{refund_id} GetPaymentRefund
SquareConnect.RefundsApi listPaymentRefunds GET /v2/refunds ListPaymentRefunds
SquareConnect.RefundsApi refundPayment POST /v2/refunds RefundPayment
SquareConnect.ReportingApi listAdditionalRecipientReceivableRefunds GET /v2/locations/{location_id}/additional-recipient-receivable-refunds ListAdditionalRecipientReceivableRefunds
SquareConnect.ReportingApi listAdditionalRecipientReceivables GET /v2/locations/{location_id}/additional-recipient-receivables ListAdditionalRecipientReceivables
SquareConnect.TransactionsApi captureTransaction POST /v2/locations/{location_id}/transactions/{transaction_id}/capture CaptureTransaction
SquareConnect.TransactionsApi charge POST /v2/locations/{location_id}/transactions Charge
SquareConnect.TransactionsApi createRefund POST /v2/locations/{location_id}/transactions/{transaction_id}/refund CreateRefund
SquareConnect.TransactionsApi listRefunds GET /v2/locations/{location_id}/refunds ListRefunds
SquareConnect.TransactionsApi listTransactions GET /v2/locations/{location_id}/transactions ListTransactions
SquareConnect.TransactionsApi retrieveTransaction GET /v2/locations/{location_id}/transactions/{transaction_id} RetrieveTransaction
SquareConnect.TransactionsApi voidTransaction POST /v2/locations/{location_id}/transactions/{transaction_id}/void VoidTransaction
SquareConnect.V1EmployeesApi createEmployee POST /v1/me/employees CreateEmployee
SquareConnect.V1EmployeesApi createEmployeeRole POST /v1/me/roles CreateEmployeeRole
SquareConnect.V1EmployeesApi createTimecard POST /v1/me/timecards CreateTimecard
SquareConnect.V1EmployeesApi deleteTimecard DELETE /v1/me/timecards/{timecard_id} DeleteTimecard
SquareConnect.V1EmployeesApi listCashDrawerShifts GET /v1/{location_id}/cash-drawer-shifts ListCashDrawerShifts
SquareConnect.V1EmployeesApi listEmployeeRoles GET /v1/me/roles ListEmployeeRoles
SquareConnect.V1EmployeesApi listEmployees GET /v1/me/employees ListEmployees
SquareConnect.V1EmployeesApi listTimecardEvents GET /v1/me/timecards/{timecard_id}/events ListTimecardEvents
SquareConnect.V1EmployeesApi listTimecards GET /v1/me/timecards ListTimecards
SquareConnect.V1EmployeesApi retrieveCashDrawerShift GET /v1/{location_id}/cash-drawer-shifts/{shift_id} RetrieveCashDrawerShift
SquareConnect.V1EmployeesApi retrieveEmployee GET /v1/me/employees/{employee_id} RetrieveEmployee
SquareConnect.V1EmployeesApi retrieveEmployeeRole GET /v1/me/roles/{role_id} RetrieveEmployeeRole
SquareConnect.V1EmployeesApi retrieveTimecard GET /v1/me/timecards/{timecard_id} RetrieveTimecard
SquareConnect.V1EmployeesApi updateEmployee PUT /v1/me/employees/{employee_id} UpdateEmployee
SquareConnect.V1EmployeesApi updateEmployeeRole PUT /v1/me/roles/{role_id} UpdateEmployeeRole
SquareConnect.V1EmployeesApi updateTimecard PUT /v1/me/timecards/{timecard_id} UpdateTimecard
SquareConnect.V1ItemsApi adjustInventory POST /v1/{location_id}/inventory/{variation_id} AdjustInventory
SquareConnect.V1ItemsApi applyFee PUT /v1/{location_id}/items/{item_id}/fees/{fee_id} ApplyFee
SquareConnect.V1ItemsApi applyModifierList PUT /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} ApplyModifierList
SquareConnect.V1ItemsApi createCategory POST /v1/{location_id}/categories CreateCategory
SquareConnect.V1ItemsApi createDiscount POST /v1/{location_id}/discounts CreateDiscount
SquareConnect.V1ItemsApi createFee POST /v1/{location_id}/fees CreateFee
SquareConnect.V1ItemsApi createItem POST /v1/{location_id}/items CreateItem
SquareConnect.V1ItemsApi createModifierList POST /v1/{location_id}/modifier-lists CreateModifierList
SquareConnect.V1ItemsApi createModifierOption POST /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options CreateModifierOption
SquareConnect.V1ItemsApi createPage POST /v1/{location_id}/pages CreatePage
SquareConnect.V1ItemsApi createVariation POST /v1/{location_id}/items/{item_id}/variations CreateVariation
SquareConnect.V1ItemsApi deleteCategory DELETE /v1/{location_id}/categories/{category_id} DeleteCategory
SquareConnect.V1ItemsApi deleteDiscount DELETE /v1/{location_id}/discounts/{discount_id} DeleteDiscount
SquareConnect.V1ItemsApi deleteFee DELETE /v1/{location_id}/fees/{fee_id} DeleteFee
SquareConnect.V1ItemsApi deleteItem DELETE /v1/{location_id}/items/{item_id} DeleteItem
SquareConnect.V1ItemsApi deleteModifierList DELETE /v1/{location_id}/modifier-lists/{modifier_list_id} DeleteModifierList
SquareConnect.V1ItemsApi deleteModifierOption DELETE /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} DeleteModifierOption
SquareConnect.V1ItemsApi deletePage DELETE /v1/{location_id}/pages/{page_id} DeletePage
SquareConnect.V1ItemsApi deletePageCell DELETE /v1/{location_id}/pages/{page_id}/cells DeletePageCell
SquareConnect.V1ItemsApi deleteVariation DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id} DeleteVariation
SquareConnect.V1ItemsApi listCategories GET /v1/{location_id}/categories ListCategories
SquareConnect.V1ItemsApi listDiscounts GET /v1/{location_id}/discounts ListDiscounts
SquareConnect.V1ItemsApi listFees GET /v1/{location_id}/fees ListFees
SquareConnect.V1ItemsApi listInventory GET /v1/{location_id}/inventory ListInventory
SquareConnect.V1ItemsApi listItems GET /v1/{location_id}/items ListItems
SquareConnect.V1ItemsApi listModifierLists GET /v1/{location_id}/modifier-lists ListModifierLists
SquareConnect.V1ItemsApi listPages GET /v1/{location_id}/pages ListPages
SquareConnect.V1ItemsApi removeFee DELETE /v1/{location_id}/items/{item_id}/fees/{fee_id} RemoveFee
SquareConnect.V1ItemsApi removeModifierList DELETE /v1/{location_id}/items/{item_id}/modifier-lists/{modifier_list_id} RemoveModifierList
SquareConnect.V1ItemsApi retrieveItem GET /v1/{location_id}/items/{item_id} RetrieveItem
SquareConnect.V1ItemsApi retrieveModifierList GET /v1/{location_id}/modifier-lists/{modifier_list_id} RetrieveModifierList
SquareConnect.V1ItemsApi updateCategory PUT /v1/{location_id}/categories/{category_id} UpdateCategory
SquareConnect.V1ItemsApi updateDiscount PUT /v1/{location_id}/discounts/{discount_id} UpdateDiscount
SquareConnect.V1ItemsApi updateFee PUT /v1/{location_id}/fees/{fee_id} UpdateFee
SquareConnect.V1ItemsApi updateItem PUT /v1/{location_id}/items/{item_id} UpdateItem
SquareConnect.V1ItemsApi updateModifierList PUT /v1/{location_id}/modifier-lists/{modifier_list_id} UpdateModifierList
SquareConnect.V1ItemsApi updateModifierOption PUT /v1/{location_id}/modifier-lists/{modifier_list_id}/modifier-options/{modifier_option_id} UpdateModifierOption
SquareConnect.V1ItemsApi updatePage PUT /v1/{location_id}/pages/{page_id} UpdatePage
SquareConnect.V1ItemsApi updatePageCell PUT /v1/{location_id}/pages/{page_id}/cells UpdatePageCell
SquareConnect.V1ItemsApi updateVariation PUT /v1/{location_id}/items/{item_id}/variations/{variation_id} UpdateVariation
SquareConnect.V1LocationsApi listLocations GET /v1/me/locations ListLocations
SquareConnect.V1LocationsApi retrieveBusiness GET /v1/me RetrieveBusiness
SquareConnect.V1TransactionsApi createRefund POST /v1/{location_id}/refunds CreateRefund
SquareConnect.V1TransactionsApi listBankAccounts GET /v1/{location_id}/bank-accounts ListBankAccounts
SquareConnect.V1TransactionsApi listOrders GET /v1/{location_id}/orders ListOrders
SquareConnect.V1TransactionsApi listPayments GET /v1/{location_id}/payments ListPayments
SquareConnect.V1TransactionsApi listRefunds GET /v1/{location_id}/refunds ListRefunds
SquareConnect.V1TransactionsApi listSettlements GET /v1/{location_id}/settlements ListSettlements
SquareConnect.V1TransactionsApi retrieveBankAccount GET /v1/{location_id}/bank-accounts/{bank_account_id} RetrieveBankAccount
SquareConnect.V1TransactionsApi retrieveOrder GET /v1/{location_id}/orders/{order_id} RetrieveOrder
SquareConnect.V1TransactionsApi retrievePayment GET /v1/{location_id}/payments/{payment_id} RetrievePayment
SquareConnect.V1TransactionsApi retrieveSettlement GET /v1/{location_id}/settlements/{settlement_id} RetrieveSettlement
SquareConnect.V1TransactionsApi updateOrder 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 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 WithHttpInfo suffix. Hence listEmployeeRoles would be called listEmployeeRolesWithHttpInfo. This method returns a CompleteResponse object with the response data deserialized along with a helper to retrieve the token if present.

  2. Use var batchToken = completeResponse.batch_token; to extract the token and proceed to get the following page if a token is present.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = "YOUR ACCESS TOKEN";


var api = new SquareConnect.V1EmployeesApi();

var opts = {
  order: "order_example",
  limit: 56,
  batch_token: null
}

function getAllEmployeeRoles(batch_token){
  if (batch_token) {
    api.listEmployeeRolesWithHttpInfo(opts).then(function(resp) {
       var batch_token = resp.batch_token;
       opts['batch_token'] = batch_token;
       getAllEmployeeRoles(token);
    }, function(error) {
      console.error(error);
    });
  }
}

getAllEmployeeRoles(true);

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.
You can’t perform that action at this time.