Square Connect Node.js SDK - RETIRED

---

NOTICE: The Square Connect Node.js SDK is retired and replaced by square/square-nodejs-sdk

This Connect Node.js SDK is retired as of 2021-04-21 and will not receive any updates. To continue receiving API and SDK improvements, bug fixes, and security patches, please follow the instructions below to migrate to the new Square Node.js SDK.

The old Connect SDK documentation is available under the /docs folder.

---

• Migrate to the Square Node.js SDK
  • Install the SDK
  • Update your code
• Example code migration
• Ask the Community

---

Migrate to the Square Node.js SDK

Follow the instructions below to migrate your apps from this retired Connect Node.js SDK to the new Square Node.js SDK. You will need to install the new SDK and update your application code.

Install the Square Node.js SDK

$ npm install square

Update your application code

Make the following changes to migrate your application code to the new Square SDK:

1. Change all instances that import the square-connect library to import the square library.
2. Update the instantiation and initialization of the API client to follow the method described below.
3. Replace square-connect models with the new square equivalents with camel case parameter names.
4. Update code for calling Square APIs and accessing response data to follow the method described below.

Note: The new SDK supports TypeScript. It exports type files that you can use to type-check the SDK usage in TypeScript codebases.

Client instantiation and initialization

Use the following examples to compare client instantiation and initialization in the retired SDK versus the new SDK.

Retired Connect SDK

This is how you import the square-connect library, and instantiate and initialize the API client.

varSquareConnect=require('square-connect');vardefaultClient=SquareConnect.ApiClient.instance;// To access sandbox resources, set the basePath to the sandbox URL//defaultClient.basePath = 'https://connect.squareupsandbox.com';// Configure OAuth2 access token for authorization: oauth2varoauth2=defaultClient.authentications['oauth2'];oauth2.accessToken=process.env.SQUARE_ACCESS_TOKEN;

New Square SDK

This is how you can do the same thing with the new square library. You can import using the ES module or CommonJS module syntax, but you should not mix the two import styles in the same codebase.

Option 1: ES module import example (recommended)

import{ApiError,Client,Environment}from'square'constclient=newClient({timeout:3000,environment: Environment.Production,// `Environment.Sandbox` to access sandbox resourcesaccessToken: process.env.SQUARE_ACCESS_TOKEN,})

Option 2: CommonJS module import example

const{ ApiError, Client, Environment }=require('square')constclient=newClient({timeout:3000,environment: Environment.Production,// `Environment.Sandbox` to access sandbox resourcesaccessToken: process.env.SQUARE_ACCESS_TOKEN,})

Example code migration

As a specific example, consider the code for creating a customer in the sandbox environment.

Retired Connect SDK

The following example uses the square-connect library to create a customer.

varSquareConnect=require('square-connect');// Instantiate and initialize the API clientvardefaultClient=SquareConnect.ApiClient.instance;defaultClient.basePath='https://connect.squareupsandbox.com';varoauth2=defaultClient.authentications['oauth2'];oauth2.accessToken=process.env.SQUARE_ACCESS_TOKEN;// Unique key to ensure this operation runs only once if you need to retryvaridempotencyKey="unique_key";varrequestBody=SquareConnect.CreateCustomerRequest.constructFromObject({idempotency_key: idempotencyKey,// Parameters use snake casegiven_name: "Amelia",family_name: "Earhart",email_address: "Amelia.Earhart@aviators.com"});// Get an instance of the Square API you want callvarcustomersApi=newSquareConnect.CustomersApi();// Call the APIcustomersApi.createCustomer(requestBody).then(function(result){console.log('API called successfully. Returned data: '+JSON.stringify(result,0,1));},function(error){console.error(error);});

New Square SDK

Now consider equivalent code that uses the new square library. Note the following:

• Calls to a Square API must be wrapped in an asynchronous function.
• Parameter names must be changed from snake case to camel case, for example from location_id to locationId.
• Square API calls return an ApiResponse or throw an ApiError. Use a try/catch statement to check whether the response succeeded or failed. Both objects contain properties that describe the request (headers and request) and the response (statusCode, body, and result). The response payload is returned as text in the body property or as a dictionary in the result property.

import{ApiError,Client,Environment}from'square'// Instantiate and initialize the API clientconstclient=newClient({environment: Environment.Sandbox,accessToken: process.env.SQUARE_ACCESS_TOKEN,})// Get an instance of the Square API you want callconst{ customersApi }=client// Unique key to ensure this operation runs only once if you need to retryletidempotencyKey="unique_key"// Call the API from within an async functionconstcreateCustomer=async()=>{letrequestBody={idempotencyKey: idempotencyKey,// Parameters use camel casegivenName: "Amelia",familyName: "Earhart",emailAddress: "Amelia.Earhart@aviators.com"}// Use a try/catch statement to check if the response succeeded or failedtry{let{ result }=awaitcustomersApi.createCustomer(requestBody)console.log('API called successfully. Returned data: 'result)}catch(error){if(errorinstanceofApiError){console.log("Errors: ",error.errors)}else{console.log("Unexpected Error: ",error)}}}createCustomer()

That's it!

For more information about using the new Square SDK, see the Square Node.js SDK on GitHub.

For more examples that use the new Square SDK, see the Square Connect API Examples on GitHub.

---

Ask the community

Please join us in our Square developer community if you have any questions or feedback!