Javascript client library for the Square Connect APIs https://docs.connect.squareup.com/
Clone or download

README.md

Square Connect Node SDK Build Statusnpm 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

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: ' + data);
}, function(error) {
  console.error(error);
});

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.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.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.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 Creates an employee for a business.
SquareConnect.V1EmployeesApi createEmployeeRole POST /v1/me/roles Creates an employee role you can then assign to employees.
SquareConnect.V1EmployeesApi createTimecard POST /v1/me/timecards Creates a timecard for an employee. Each timecard corresponds to a single shift.
SquareConnect.V1EmployeesApi deleteTimecard 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 listCashDrawerShifts 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 listEmployeeRoles GET /v1/me/roles Provides summary information for all of a business's employee roles.
SquareConnect.V1EmployeesApi listEmployees GET /v1/me/employees Provides summary information for all of a business's employees.
SquareConnect.V1EmployeesApi listTimecardEvents GET /v1/me/timecards/{timecard_id}/events Provides summary information for all events associated with a particular timecard.
SquareConnect.V1EmployeesApi listTimecards GET /v1/me/timecards Provides summary information for all of a business's employee timecards.
SquareConnect.V1EmployeesApi retrieveCashDrawerShift 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 retrieveEmployee GET /v1/me/employees/{employee_id} Provides the details for a single employee.
SquareConnect.V1EmployeesApi retrieveEmployeeRole GET /v1/me/roles/{role_id} Provides the details for a single employee role.
SquareConnect.V1EmployeesApi retrieveTimecard GET /v1/me/timecards/{timecard_id} Provides the details for a single timecard.
SquareConnect.V1EmployeesApi updateEmployee PUT /v1/me/employees/{employee_id} V1 UpdateEmployee
SquareConnect.V1EmployeesApi updateEmployeeRole PUT /v1/me/roles/{role_id} Modifies the details of an employee role.
SquareConnect.V1EmployeesApi updateTimecard 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 adjustInventory POST /v1/{location_id}/inventory/{variation_id} Adjusts an item variation's current available inventory.
SquareConnect.V1ItemsApi applyFee 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 applyModifierList 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 createCategory POST /v1/{location_id}/categories Creates an item category.
SquareConnect.V1ItemsApi createDiscount POST /v1/{location_id}/discounts Creates a discount.
SquareConnect.V1ItemsApi createFee POST /v1/{location_id}/fees Creates a fee (tax).
SquareConnect.V1ItemsApi createItem POST /v1/{location_id}/items Creates an item and at least one variation for it.
SquareConnect.V1ItemsApi createModifierList POST /v1/{location_id}/modifier-lists Creates an item modifier list and at least one modifier option for it.
SquareConnect.V1ItemsApi createModifierOption 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 createPage POST /v1/{location_id}/pages Creates a Favorites page in Square Register.
SquareConnect.V1ItemsApi createVariation POST /v1/{location_id}/items/{item_id}/variations Creates an item variation for an existing item.
SquareConnect.V1ItemsApi deleteCategory DELETE /v1/{location_id}/categories/{category_id} Deletes an existing item category.
SquareConnect.V1ItemsApi deleteDiscount DELETE /v1/{location_id}/discounts/{discount_id} Deletes an existing discount.
SquareConnect.V1ItemsApi deleteFee DELETE /v1/{location_id}/fees/{fee_id} Deletes an existing fee (tax).
SquareConnect.V1ItemsApi deleteItem DELETE /v1/{location_id}/items/{item_id} Deletes an existing item and all item variations associated with it.
SquareConnect.V1ItemsApi deleteModifierList DELETE /v1/{location_id}/modifier-lists/{modifier_list_id} Deletes an existing item modifier list and all modifier options associated with it.
SquareConnect.V1ItemsApi deleteModifierOption 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 deletePage DELETE /v1/{location_id}/pages/{page_id} Deletes an existing Favorites page and all of its cells.
SquareConnect.V1ItemsApi deletePageCell DELETE /v1/{location_id}/pages/{page_id}/cells Deletes a cell from a Favorites page in Square Register.
SquareConnect.V1ItemsApi deleteVariation DELETE /v1/{location_id}/items/{item_id}/variations/{variation_id} Deletes an existing item variation from an item.
SquareConnect.V1ItemsApi listCategories GET /v1/{location_id}/categories Lists all of a location's item categories.
SquareConnect.V1ItemsApi listDiscounts GET /v1/{location_id}/discounts Lists all of a location's discounts.
SquareConnect.V1ItemsApi listFees GET /v1/{location_id}/fees Lists all of a location's fees (taxes).
SquareConnect.V1ItemsApi listInventory GET /v1/{location_id}/inventory Provides inventory information for all of a merchant's inventory-enabled item variations.
SquareConnect.V1ItemsApi listItems GET /v1/{location_id}/items Provides summary information for all of a location's items.
SquareConnect.V1ItemsApi listModifierLists GET /v1/{location_id}/modifier-lists Lists all of a location's modifier lists.
SquareConnect.V1ItemsApi listPages GET /v1/{location_id}/pages Lists all of a location's Favorites pages in Square Register.
SquareConnect.V1ItemsApi removeFee 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 removeModifierList 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 retrieveItem GET /v1/{location_id}/items/{item_id} Provides the details for a single item, including associated modifier lists and fees.
SquareConnect.V1ItemsApi retrieveModifierList GET /v1/{location_id}/modifier-lists/{modifier_list_id} Provides the details for a single modifier list.
SquareConnect.V1ItemsApi updateCategory PUT /v1/{location_id}/categories/{category_id} Modifies the details of an existing item category.
SquareConnect.V1ItemsApi updateDiscount PUT /v1/{location_id}/discounts/{discount_id} Modifies the details of an existing discount.
SquareConnect.V1ItemsApi updateFee PUT /v1/{location_id}/fees/{fee_id} Modifies the details of an existing fee (tax).
SquareConnect.V1ItemsApi updateItem PUT /v1/{location_id}/items/{item_id} Modifies the core details of an existing item.
SquareConnect.V1ItemsApi updateModifierList PUT /v1/{location_id}/modifier-lists/{modifier_list_id} Modifies the details of an existing item modifier list.
SquareConnect.V1ItemsApi updateModifierOption 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 updatePage PUT /v1/{location_id}/pages/{page_id} Modifies the details of a Favorites page in Square Register.
SquareConnect.V1ItemsApi updatePageCell PUT /v1/{location_id}/pages/{page_id}/cells Modifies a cell of a Favorites page in Square Register.
SquareConnect.V1ItemsApi updateVariation PUT /v1/{location_id}/items/{item_id}/variations/{variation_id} Modifies the details of an existing item variation.
SquareConnect.V1LocationsApi listLocations GET /v1/me/locations Provides details for a business's locations, including their IDs.
SquareConnect.V1LocationsApi retrieveBusiness GET /v1/me Get a business's information.
SquareConnect.V1TransactionsApi createRefund 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 listBankAccounts 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 listOrders GET /v1/{location_id}/orders Provides summary information for a merchant's online store orders.
SquareConnect.V1TransactionsApi listPayments 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 listRefunds 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 listSettlements 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 retrieveBankAccount 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 retrieveOrder GET /v1/{location_id}/orders/{order_id} Provides comprehensive information for a single online store order, including the order's history.
SquareConnect.V1TransactionsApi retrievePayment GET /v1/{location_id}/payments/{payment_id} Provides comprehensive information for a single payment.
SquareConnect.V1TransactionsApi retrieveSettlement 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 updateOrder 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 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.