Node.js SDK Migration Guide

Version 40.0.0 of the Node.js SDK represents a full rewrite of the SDK with a number of breaking changes, outlined in the following sections. When upgrading to this version or later versions, take note of the changes in the SDK, including client construction and parameter names. If necessary, you can use the legacy version of the SDK along with the latest version.

SDK versions 39.1.0 and earlier continue to function as expected, but you should plan to update your integration as soon as possible to ensure continued support.

The new Client class has some breaking changes and is constructed in a slightly different way than the legacy version of the SDK.

// LEGACY
import { Client, Environment } from "square/legacy";
const client = new Client({
  bearerAuthCredentials: {
    accessToken: process.env.SQUARE_ACCESS_TOKEN,
  },
  environment: Environment.Sandbox,
});

// NEW
import { SquareClient, SquareEnvironment } from "square";
const client = new SquareClient({
  token: process.env.SQUARE_ACCESS_TOKEN,
  environment: SquareEnvironment.Sandbox,
});

While the new SDK has many improvements, we understand that it takes time to upgrade when there are breaking changes. To make the migration easier, the new SDK exports the legacy SDK as square/legacy. The following example shows how to use the new and legacy SDKs inside a single file:

import { randomUUID } from "crypto";
import { Square, SquareClient } from "square";
import { Client } from "square/legacy";

const client = new SquareClient({
  token: process.env.SQUARE_ACCESS_TOKEN,
});

const legacyClient = new Client({
  bearerAuthCredentials: {
    accessToken: process.env.SQUARE_ACCESS_TOKEN!,
  },
});

async function getLocation(): Promise<Square.Location> {
  return (
    await client.locations.get({
      locationId: "YOUR_LOCATION_ID",
    })
  ).location!;
}

async function createOrder() {
  const location = await getLocation();
  await legacyClient.ordersApi.createOrder({
    idempotencyKey: randomUUID(),
    order: {
      locationId: location.id!,
      lineItems: [
        {
          name: "New Item",
          quantity: "1",
          basePriceMoney: {
            amount: BigInt(100),
            currency: "USD",
          },
        },
      ],
    },
  });
}

createOrder();

You should migrate to the new SDK using the following steps:

1. Upgrade the NPM module to ^40.0.0.

2. Search and replace all requires and imports from "square" to "square/legacy".

   • For required, replace require("square") with require("square/legacy").
   • For imports, replace from "square" with from "square/legacy".
   • For dynamic imports, replace import("square") with import("square/legacy").

3. Gradually introduce methods from the new SDK by importing them from "square".

The previous version of the SDK relied on many positional parameters, which made it difficult for readers to understand the meaning of the parameter. For example:

// LEGACY
await client.customersApi.listCustomers(undefined, 10, undefined, "DESC");

It's not immediately clear what undefined, 10, undefined, and DESC mean. In the new version of the SDK, you specify the parameters by their name and you're not required to pass undefined parameters. The same ListCustomers request looks like the following:

// NEW
await client.customers.list({
  limit: 10,
  sortOrder: "DESC",
});

Previously, API classes were named after the resource you're interacting with and suffixed with Api. To interact with customer resources, you used the client.customersApi class.

The method was named based on the action you want to perform and the same resource name specified earlier. To list customers, you call client.customersApi.listCustomers.

// LEGACY
await client.customersApi.listCustomers();

The new API classes are named by the resource without the Api suffix, and the methods now name the action without mentioning the resource a second time.

// NEW
await client.customers.list();

When interacting with a nested resource, you can chain the resources using dot-notation.

// NEW
await client.customers.groups.list();

To find all classes and method names that might have changed, see