square

Square Node.js SDK

Use this JavaScript library to manage Square resources (such as payments, orders, items, and inventory) for your own Square account or on behalf of Square sellers.

Requirements

The SDK requires Node.js version 10 or later.

We intend to update the SDK to support the current and LTS versions of Node.js while dropping support for versions that have reached their EOL.

Does the SDK support TypeScript?

Yes.

The SDK package also exports the type files which help type-check the SDK usage in TypeScript codebases and provide hints in JavaScript codebases in supported IDEs.

Installation

Install the latest SDK using npm:

$ npm install square

How do I import the client and other types from the SDK?

Recommended: You can import the client in ES module style if your environment supports it:

import { Client, Environment } from 'square'

Or you can import the client in CommonJS style:

const { Client, Environment } = require('square')

Import Gotcha

Do not mix ES module and CommonJS imports in the same codebase. This will likely cause issues that are hard to debug. For more information, do a web search for "Dual Package Hazard Node".

How do I initialize the client?

import { Client, Environment } from 'square'

const client = new Client({
  environment: Environment.Sandbox,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

How can I update the access token or some other configuration in the client?

You should not attempt to modify an existing client instance. Instead, create a new instance using the withConfiguration method:

import { Client } from 'square'

const client = new Client(/** some config **/)

// After getting the access token...
const newClient = client.withConfiguration({
  accessToken: newlyAcquiredAccessTokenValue,
})

withConfiguration copies over the existing configuration and state with the given configuration overrides.

API documentation

Payments

• Payments
• Refunds
• Disputes
• Checkout
• Apple Pay
• Terminal

Orders

• Orders

Subscriptions

• Subscriptions

Invoices

• Invoices

Items

• Catalog
• Inventory

Customers

• Customers
• Customer Groups
• Customer Segments

Loyalty

• Loyalty

Bookings

• Bookings

Business

• Merchants
• Locations
• Devices

Team

• Team
• Employees
• Labor
• Cash Drawers

Financials

• Bank Accounts

Authorization APIs

• Mobile Authorization
• O Auth

Deprecated APIs

• V1 Employees
• V1 Transactions
• V1 Items
• Transactions

Usage

First time using Square? Here’s how to get started:

1. Create a Square account. If you don’t have one already, sign up for a developer account.
2. Create an application. Go to your Developer Dashboard and create your first application. All you need to do is give it a name. When you’re doing this for your production application, enter the name as you would want a customer to see it.
3. Make your first API call. You’ll make your first call to listLocations to get a location ID, which is required by many Square API calls. For more information about locations, see the Locations overview.

Now let’s call your first Square API. Open your favorite text editor, create a new file called locations.js, and copy the following code into that file:

import { ApiError, Client, Environment } from 'square'
 
// Create an instance of the API Client 
// and initialize it with the credentials 
// for the Square account whose assets you want to manage
const client = new Client({
  timeout:3000,
  environment: Environment.Sandbox,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})
 
// Get an instance of the Square API you want call
const { locationsApi } = client

// Create wrapper async function 
const getLocations = async () => {
  // The try/catch statement needs to be called from within an asynchronous function
  try {
    // Call listLocations method to get all locations in this Square account
    let listLocationsResponse = await locationsApi.listLocations()

    // Get first location from list
    let firstLocation = listLocationsResponse.result.locations[0]

    console.log("Here is your first location: ", firstLocation)
  } catch (error) {
    if (error instanceof ApiError) {
      console.log("There was an error in your request: ", error.errors)
    } else {
      console.log("Unexpected Error: ", error)
    }
  }
}

// Invokes the async function
getLocations()

Next, get an access token and reference it in your code. To call the Square API, you need to get an access token and initialize the API Client class with that token. An application has two sets of credentials: production and sandbox. To get started, you’ll use your sandbox access token so you can try things out in a test environment that is completely separate from production resources. Here’s how:

1. Go back to your application in the Developer Dashboard.

2. View the details of your application.

3. Make sure that Sandbox is selected at the top of the page.

4. In the Sandbox Access Token box, click Show to display the token.

5. Copy the sandbox access token.

6. Set the environment variable SQUARE_ACCESS_TOKEN with that token:

   export SQUARE_ACCESS_TOKEN="YOUR SANDBOX ACCESS TOKEN HERE"
   

You’ll notice in locations.js that the Client object is initialized with the environment set to sandbox. You use the environment parameter to specify whether you want to access production or sandbox resources.

Important When you eventually switch from trying things out on sandbox to actually working with your real production resources, you should not embed the access token in your code. Make sure you store and access your production access tokens securely.

Now save locations.js and run it:

node locations.js

If your call is successful, you’ll get a response that looks like this:

Here is your first location:  { 
  id: 'LOCATION_ID',
  name: 'Default Test Account',
  timezone: 'Etc/UTC',
  capabilities: [ 'CREDIT_CARD_PROCESSING' ],
  status: 'ACTIVE',
  createdAt: '2019-07-23T19:46:48Z',
  merchantId: "YOUR_MERCHANT_ID",
  country: 'US',
  languageCode: 'en-US',
  currency: 'USD',
  type: 'PHYSICAL',
  businessHours: {},
  mcc: '7299' }

Yay! You successfully made your first call. If you didn’t, you would see an error message that looks something like this:

There was an error in your request:  { errors:
   [ { category: 'AUTHENTICATION_ERROR',
       code: 'UNAUTHORIZED',
       detail: 'This request could not be authorized.' } ] }

This error was returned when an invalid token was used to call the API.

After you’ve tried out the Square APIs and tested your application using sandbox, you will want to switch to your production credentials so you can manage real Square resources. Don't forget to switch your access token from sandbox to production for real data.

SDK patterns

If you know a few patterns, you’ll be able to call any API in the SDK. Here are some important ones:

Get an access token

To use the Square API to manage the resources (such as payments, orders, customers, etc.) of a Square account, you need to create an application (or use an existing one) in the Developer Dashboard and get an access token for the application.

When you call a Square API, you provide an access token that is appropriate for your use case. An access token has specific permissions to resources in a specific Square account. There are two options:

• To manage the resources for your own Square account, use the access token (sandbox or production) for the application created in your Square account.
• To manage resources for other Square accounts, use OAuth to ask owners of the accounts you want to manage to allow you to work on their behalf. When you implement OAuth, you ask the Square account holder for permission to manage resources in their account (you can request access to specific resources) and get an OAuth access token and refresh token for their account. For more information, see the OAuth overview.

Important For both use cases, make sure you store and access the tokens securely.

Import and Instantiate the Client Class

To use the Square API, you import the Client class, instantiate a Client object, and initialize it with the appropriate access token and environment. Here’s how:

1. Import the Client class from the Square JS SDK module so you can call the Square API:

   import { Client } from 'square'
   

2. Instantiate a Client object and initialize it with the access token for the Square account whose resources you want to manage and the environment that you want to use.

To access sandbox resources, initialize the Client with environment set to sandbox:

import { Client, Environment } from 'square'

const client = new Client({
  environment: Environment.Sandbox,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

To access production resources, set environment to production:

import { Client, Environment } from 'square'

const client = new Client({
  environment: Environment.Production,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

To set a custom environment provide a customUrl, and set the environment to Environment.Custom:

import { Client, Environment } from 'square'

const client = new Client({
  environment: Environment.Custom,
  customUrl: "https://your.customdomain.com",
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

Get an instance of an API object and call its methods

Each API is implemented as a class. The Client object instantiates every API class and exposes them as properties so you can easily start using any Square API. You work with an API by calling methods on an instance of an API class. Here’s how:

Work with an API by calling the methods on the API object. For example, you would call listCustomers to get a list of all customers in the Square account:

import { ApiError, Client, Environment } from 'square'

const client = new Client({
  environment: Environment.Sandbox,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

// Get an instance of the Square API you want call
const { customersApi }  = client
const listCustomers = async () => {
  try {
    // Returns and API response object. API call value is on the result property
    let { result } = await customersApi.listCustomers()
    console.log(result)
  } catch (error) {
    if (error instanceof ApiError) {
      console.log(error.errors)
    } else {
      console.log("Unexpected Error: ", error)
    }
  }
}
listCustomers()

See the SDK documentation for the list of methods for each API class.

Pass complex parameters (such as create, update, search, etc.) as a dictionary. For example, you would pass a dictionary containing the values used to create a new customer using createCustomer:

import { ApiError, Client, Environment } from 'square'

// Create a unique key for this creation operation so you don't accidentally
// create the customer multiple times if you need to retry this operation.
// Here we use the npm package uuid
import { v4 as uuidv4 } from 'uuid'

const client = new Client({
  environment: Environment.Sandbox,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

let idempotencyKey = uuidv4()

const createCustomer = async () => {
  // To create a customer, you only need 1 of 5 identity values but you'll be
  // specifying two.
  let requestBody = {
    idempotencyKey: idempotencyKey, // A unique id for the request
    givenName: "Amelia",
    familyName: "Earhart"
  }

  try {
    let { result } = await customersApi.createCustomer(requestBody)
    console.log(result)
  } catch (error) {
    if (error instanceof ApiError) {
      console.log(error.errors)
    } else {
      console.log("Unexpected Error: ", error)
    }
  }
}
createCustomer()

If your call succeeds, you’ll see a response that looks like this:

{
  'customer': {
    'createdAt': '2019-06-28T21:23:05.126Z',
    'creationSource': 'THIRD_PARTY',
    'familyName': 'Earhart',
    'givenName': 'Amelia',
    'id': 'CBASEDwl3El91nohQ2FLEk4aBfcgAQ',
    'preferences': {
      'emailUnsubscribed': False
    },
    'updatedAt': '2019-06-28T21:23:05.126Z'
  }
}

Use idempotency for create, update, or other calls that you want to avoid calling twice. To make an idempotent API call, you add the idempotencyKey with a unique value in the Hash for the API call’s request. Many operations require an idempotencyKey.

Specify a location ID for APIs such as Transactions, Orders, and Checkout that deal with payments. When a payment or order is created in Square, it is always associated with a location. Many operations require a location ID.

Handle the response

API calls return an ApiResponse or throw an ApiError. ApiResponse and ApiError objects both contain properties that describe both the request (headers and request) and the response (statusCode, body, and result). ApiErrors are thrown when the statusCode of the response is out of the 200s range. Here’s how to handle the response:

Use a try/catch statement to check whether the response succeeded or failed:

try {
  let { result } = await customersApi.createCustomer(requestBody) 
  // If successful we will display response result
  console.log(result)
} catch (error) {
  if (error instanceof ApiError) {
    // If unsuccessful we will display the list of errors
    console.log("Errors: ", error.errors)
  } else {
    console.log("Unexpected Error: ", error)
  }
}

Read the response payload. The response payload is returned as text in the body property or as a dictionary in the result property. For retrieve calls, a dictionary containing a single item is returned with a key name that is the name of the object (for example, customer). For list calls, an object containing a list of objects is returned with a key name that is the plural of the object name (for example, customers). If there are no objects for a list call to return, it returns an empty dictionary.

Check the cursor for list operations. Make sure you get all items returned in a list call by checking the cursor value returned in the API response. When you call a list API the first time, you set the cursor to an empty string in the API request. If the API response contains a cursor value, you call the API again to get the next page of items and continue to call that API again until the cursor is not returned in the API response. Here’s a code snippet that calls listCustomers to count the total number of customers:

import { ApiError, Client, Environment } from 'square'

const client = new Client({
  environment: Environment.Sandbox,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

// Get an instance of the Square API you want call
const { customersApi }  = client

const tallyUpCustomers = async  () => {
  // Initialize the customer count
  let totalCustomers = 0
  // Initialize the cursor with an empty string since we are
  // calling listCustomers for the first time
  let cursor = ""
  // Count the total number of customers using the listCustomers method
  while (cursor !== null) {

    try {
      // Call listCustomers method to get all customers in this Square account
      let { result } = await customersApi.listCustomers(cursor)
      totalCustomers += result.customers.length

      // Get the cursor if it exists in the result else set it to null
      cursor = result.cursor ? result.cursor : null
      console.log(`cursor: ${cursor}`)

    } catch (error) {
      if (error instanceof ApiError) {
        console.log(`Errors: ${error.errors}`)
      } else {
        console.log("Unexpected Error: ", error)
      }

      // Exit loop once an error is encountered
      break
    }
  }

  console.log(`Total customers: ${totalCustomers}`)
}
tallyUpCustomers()

Tests

First, clone the repo locally and cd into the directory.

git clone https://github.com/square/square-nodejs-sdk.git
cd square-nodejs-sdk

Next, install dependencies and build.

npm install
npm run build

Before running the tests, get a sandbox access token from your Developer Dashboard and use it to set a SQUARE_SANDBOX_TOKEN environment variable.

export SQUARE_SANDBOX_TOKEN="YOUR SANDBOX ACCESS TOKEN HERE"

And run the tests.

npm test

Learn more

The Square Platform is built on the Square API. Square has a number of other SDKs that enable you to securely handle credit card information on both mobile and web so that you can process payments via the Square API.

You can also use the Square API to create applications or services that work with payments, orders, inventory, etc. that have been created and managed in Square’s in-person hardware products (Square Point of Sale and Square Register).