Square Node.js SDK

https://github.com/square/square-nodejs-sdk
Admin
The Square Node.js SDK provides convenient access to the Square API from TypeScript and JavaScript,...
Tokens:246,618
Snippets:1,509
Trust Score:9.4
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Create payment example

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/payments-client.md

Example of creating a payment with a card source, idempotency key, amount, app fee, autocomplete, customer, location, reference ID, and note. Logs the payment status and ID.

```typescript
const response = await client.payments.create({
    sourceId: "ccof:GaJGNaZa8x4OgDJn4GB",
    idempotencyKey: "7b0f3ec5-086a-4871-8f13-3c81b3875218",
    amountMoney: { amount: BigInt("1000"), currency: "USD" },
    appFeeMoney: { amount: BigInt("10"), currency: "USD" },
    autocomplete: true,
    customerId: "W92WH6P11H4Z77CTET0RNTGFW8",
    locationId: "L88917AVBK2S5",
    referenceId: "123456",
    note: "Brief description",
});
console.log(response.payment?.status, response.payment?.id);
```

--------------------------------

### Complete payment example

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/payments-client.md

Example call to complete a payment with a payment ID and an optional version token.

```ts
await client.payments.complete({ paymentId: "pid", versionToken: "token" });
```

--------------------------------

### Install dependencies with yarn

Source: https://github.com/square/square-nodejs-sdk/blob/master/CONTRIBUTING.md

Installs the project dependencies using the yarn package manager.

```bash
yarn install
```

--------------------------------

### Building a Page in payments.list

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/pagination.md

Representative example from payments.list (src/api/resources/payments/client/Client.ts) showing how a generated client builds a Page. It uses withRawResponse() to get raw response, defines hasNextPage based on cursor, getItems to extract payments, and loadPage to re-issue the request with the cursor.

```ts
const dataWithRawResponse = await list(request).withRawResponse();
return new core.Page<Square.Payment, Square.ListPaymentsResponse>({
    response: dataWithRawResponse.data,
    rawResponse: dataWithRawResponse.rawResponse,
    hasNextPage: (response) =>
        response?.cursor != null && !(typeof response?.cursor === "string" && response?.cursor === ""),
    getItems: (response) => response?.payments ?? [],
    loadPage: (response) => {
        return list(core.setObjectProperty(request, "cursor", response?.cursor));
    },
});
```

--------------------------------

### List payments example with pagination

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/payments-client.md

Example of calling `client.payments.list` with `locationId`, `limit`, and `sortField`. Iterates over the returned page asynchronously and logs payment ID, amount, and status.

```typescript
const page = await client.payments.list({ locationId: "L1", limit: 10, sortField: "CREATED_AT" });
for await (const payment of page) {
    console.log(payment.id, payment.totalMoney?.amount, payment.status);
}
```

--------------------------------

### Install Square TypeScript library with npm

Source: https://github.com/square/square-nodejs-sdk/blob/master/README.md

Use this command to install the Square TypeScript library as a dependency in your project. Run this in your terminal within your project directory.

```sh
npm i -s square
```

--------------------------------

### Money usage example

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/types.md

Example of creating a Money object with amount as BigInt(1250) and currency "USD".

```typescript
const money: Square.Money = { amount: BigInt(1250), currency: "USD" };
```

--------------------------------

### Start a transfer order with client.transferOrders.start

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Changes a DRAFT transfer order to STARTED status, decrementing inventory at the source location and marking it as in-transit. The order must be in DRAFT status with all required fields populated; once started, it cannot be deleted but can be canceled via CancelTransferOrder. Creates a transfer_order.updated webhook event.

```typescript
await client.transferOrders.start({
    transferOrderId: "transfer_order_id",
    idempotencyKey: "EXAMPLE_IDEMPOTENCY_KEY_789",
    version: BigInt("1753109537351")
});
```

--------------------------------

### retrieveTokenStatus usage example

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/oauth-client.md

Example usage of retrieveTokenStatus. Shows how to access token scopes and expiration, and how to handle an expired or invalid token that returns a 401 SquareError.

```ts
const status = await client.oAuth.retrieveTokenStatus();
console.log(status.scopes, status.expiresAt);

try {
    await client.oAuth.retrieveTokenStatus();
} catch (err) {
    if (err instanceof SquareError && err.statusCode === 401) {
        console.error("Token expired or invalid");
    }
}
```

--------------------------------

### Get loyalty promotion with client.loyalty.programs.promotions.get

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a specific loyalty promotion by program ID and promotion ID.

```typescript
await client.loyalty.programs.promotions.get({
    programId: "program_id",
    promotionId: "promotion_id"
});
```

--------------------------------

### PaymentsClient.RequestOptions re-export

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/base-client.md

Shows how each generated resource client re-exports BaseRequestOptions as XxxClient.RequestOptions. This example uses PaymentsClient.

```ts
export declare namespace PaymentsClient {
    export type Options = BaseClientOptions;
    export interface RequestOptions extends BaseRequestOptions {}
}
```

--------------------------------

### Create payment with error handling and raw response

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/payments-client.md

Example of using `withRawResponse()` to get the raw HTTP response. Catches `SquareError` and logs the status code and error details (category, code, detail).

```typescript
import { SquareError } from "square";

try {
    const { data, rawResponse } = await client.payments
        .create({
            sourceId: "CASH",
            idempotencyKey: "dup-key",
            amountMoney: { amount: BigInt(100), currency: "USD" },
        })
        .withRawResponse();
    console.log(data.payment?.id, rawResponse.status);
} catch (err) {
    if (err instanceof SquareError) {
        console.error(err.statusCode);
        for (const e of err.errors) {
            console.error(e.category, e.code, e.detail);
        }
    }
}
```

--------------------------------

### Create a booking (client.bookings.create)

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a booking. Required input includes Booking.location_id, Booking.start_at, Booking.AppointmentSegment.team_member_id, Booking.AppointmentSegment.service_variation_id, and Booking.AppointmentSegment.service_variation_version. Requires APPOINTMENTS_WRITE for buyer-level or APPOINTMENTS_ALL_WRITE and APPOINTMENTS_WRITE for seller-level OAuth scopes. Seller must subscribe to Appointments Plus or Appointments Premium.

```typescript
await client.bookings.create({
    booking: {}
});
```

--------------------------------

### PKCE flow with error handling example for obtainToken

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/oauth-client.md

Performs the PKCE flow with shortLived set to true to get a 24-hour token. It includes error handling that catches SquareError and logs error codes and details, such as UNAUTHORIZED on bad credentials.

```typescript
import { SquareError } from "square";

try {
    const response = await client.oAuth.obtainToken({
        clientId: "sq0idp-...",
        code: "auth-code",
        codeVerifier: "pkce-verifier",
        grantType: "authorization_code",
        shortLived: true,
    });
    console.log(response.accessToken);
} catch (err) {
    if (err instanceof SquareError) {
        for (const e of err.errors) {
            console.error(e.code, e.detail); // e.g. UNAUTHORIZED on bad credentials
        }
    }
}
```

--------------------------------

### Import SquareClient

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/index.md

Shows how to import the main SquareClient class from the package root.

```APIDOC
## Import the SquareClient

### Description
Import the main client class from the package root to access all Square API resources.

### Import Path
`square` (package root)

### Example
```ts
import { SquareClient } from "square";
```
```

--------------------------------

### Build the project with yarn

Source: https://github.com/square/square-nodejs-sdk/blob/master/CONTRIBUTING.md

Builds the project using the yarn build command.

```bash
yarn build
```

--------------------------------

### Cancel payment example

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/payments-client.md

Example call to cancel a payment by providing the payment ID.

```ts
await client.payments.cancel({ paymentId: "pid" });
```

--------------------------------

### Create a subscription with client.subscriptions.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Enrolls a customer in a subscription. If a card on file is provided, Square charges the card; otherwise, an invoice is sent. The subscription starts immediately unless `start_date` is specified.

```typescript
await client.subscriptions.create({
    idempotencyKey: "8193148c-9586-11e6-99f9-28cfe92138cf",
    locationId: "S8GWD5R9QB376",
    planVariationId: "6JHXF3B2CW3YKHDV4XEM674H",
    customerId: "CHFGVKYY8RSV93M5KCYTG4PN0G",
    startDate: "2023-06-20",
    cardId: "ccof:qy5x8hHGYsgLrp4Q4GB",
    timezone: "America/Los_Angeles",
    source: {
        name: "My Application"
    },
    phases: [{
            ordinal: BigInt("0"),
            orderTemplateId: "U2NaowWxzXwpsZU697x7ZHOAnCNZY"
        }]
});
```

--------------------------------

### Import Subpackage Client

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/index.md

Shows how to import a per-resource client from a subpackage export for tree-shaking.

```APIDOC
## Import a Subpackage Client

### Description
Import a tree-shakeable per-resource client from a subpackage export, e.g. the OAuth client.

### Import Path
`square/oAuth`

### Example
```ts
import { OAuthClient } from "square/oAuth";
```
```

--------------------------------

### Create a payment with SquareClient

Source: https://github.com/square/square-nodejs-sdk/blob/master/README.md

Instantiate the SquareClient with a token and create a payment with the provided details. The example uses a test source ID and idempotency key.

```typescript
import { SquareClient } from "square";

const client = new SquareClient({ token: "YOUR_TOKEN" });
await client.payments.create({
    sourceId: "ccof:GaJGNaZa8x4OgDJn4GB",
    idempotencyKey: "7b0f3ec5-086a-4871-8f13-3c81b3875218",
    amountMoney: {
        amount: BigInt("1000"),
        currency: "USD"
    },
    appFeeMoney: {
        amount: BigInt("10"),
        currency: "USD"
    },
    autocomplete: true,
    customerId: "W92WH6P11H4Z77CTET0RNTGFW8",
    locationId: "L88917AVBK2S5",
    referenceId: "123456",
    note: "Brief description"
});
```

--------------------------------

### Get a location with client.locations.get()

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves details of a single location. Use "main" as the location ID to get the main location.

```typescript
await client.locations.get({
    locationId: "location_id"
});
```

--------------------------------

### Create an order with client.orders.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a new order with line items, taxes, and discounts. The order can include catalog items, custom items, and applied discounts. Requires a location ID and an idempotency key.

```typescript
await client.orders.create({
    order: {
        locationId: "057P5VYJ4A5X1",
        referenceId: "my-order-001",
        lineItems: [{
                name: "New York Strip Steak",
                quantity: "1",
                basePriceMoney: {
                    amount: BigInt("1599"),
                    currency: "USD"
                }
            }, {
                quantity: "2",
                catalogObjectId: "BEMYCSMIJL46OCDV4KYIKXIB",
                modifiers: [{
                        catalogObjectId: "CHQX7Y4KY6N5KINJKZCFURPZ"
                    }],
                appliedDiscounts: [{
                        discountUid: "one-dollar-off"
                    }]
            }],
        taxes: [{
                uid: "state-sales-tax",
                name: "State Sales Tax",
                percentage: "9",
                scope: "ORDER"
            }],
        discounts: [{
                uid: "labor-day-sale",
                name: "Labor Day Sale",
                percentage: "5",
                scope: "ORDER"
            }, {
                uid: "membership-discount",
                catalogObjectId: "DB7L55ZH2BGWI4H23ULIWOQ7",
                scope: "ORDER"
            }, {
                uid: "one-dollar-off",
                name: "Sale - $1.00 off",
                amountMoney: {
                    amount: BigInt("100"),
                    currency: "USD"
                },
                scope: "LINE_ITEM"
            }]
    },
    idempotencyKey: "8193148c-9586-11e6-99f9-28cfe92138cf"
});
```

--------------------------------

### constructor(options?)

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/payments-client.md

Creates a new PaymentsClient instance. The options parameter is optional and defaults to an empty object.

```APIDOC
## Constructor

### Description
Creates a new PaymentsClient instance.

### Method
constructor

### Signature
```ts
constructor(options: PaymentsClient.Options = {});
```

### Parameters
- **options** (`PaymentsClient.Options` = `BaseClientOptions`) - Optional - Default `{}`
```

--------------------------------

### Create a payment link with quickPay

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a Square-hosted checkout page. The request includes an idempotency key and a `quickPay` object with the item name, price in the smallest currency unit (using `BigInt`), currency, and location ID.

```typescript
await client.checkout.paymentLinks.create({
    idempotencyKey: "cd9e25dc-d9f2-4430-aedb-61605070e95f",
    quickPay: {
        name: "Auto Detailing",
        priceMoney: {
            amount: BigInt("10000"),
            currency: "USD"
        },
        locationId: "A9Y43N9ABXZBP"
    }
});
```

--------------------------------

### Import Legacy SDK

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/index.md

Shows how to import the legacy SDK re-exported for migration.

```APIDOC
## Import Legacy SDK

### Description
Import the legacy SDK (v39.x API) for migration purposes.

### Import Path
`square/legacy`

### Example
```ts
import { /* legacy exports */ } from "square/legacy";
```
```

--------------------------------

### client.loyalty.accounts.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a loyalty account with the provided program ID and mapping.

```APIDOC
## client.loyalty.accounts.create

### Description
Creates a loyalty account. To create a loyalty account, you must provide the `program_id` and a `mapping` with the `phone_number` of the buyer.

### Method
POST

### Endpoint
/loyalty/accounts

### Parameters
#### Request Body
- **loyaltyAccount** (object) - Required - The loyalty account to create.
  - **programId** (string) - Required - The program ID.
  - **mapping** (object) - Required - The mapping with the phone number.
    - **phoneNumber** (string) - Required - The buyer's phone number.
- **idempotencyKey** (string) - Required - A unique idempotency key.

### Request Example
```typescript
await client.loyalty.accounts.create({
    loyaltyAccount: {
        programId: "d619f755-2d17-41f3-990d-c04ecedd64dd",
        mapping: {
            phoneNumber: "+14155551234"
        }
    },
    idempotencyKey: "ec78c477-b1c3-4899-a209-a4e71337c996"
});
```

### Response
#### Success Response (200)
- **loyaltyAccount** (object) - The created loyalty account.
- **errors** (array) - Any errors that occurred.

#### Response Example
```json
{
  "loyaltyAccount": {
    "id": "...",
    "programId": "...",
    "balance": 0,
    "lifetimePoints": 0,
    "customerId": "...",
    "enrolledAt": "...",
    "createdAt": "...",
    "updatedAt": "...",
    "mapping": {
      "phoneNumber": "..."
    }
  },
  "errors": []
}
```
```

--------------------------------

### Instantiate SquareClient with token and environment

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/square-client.md

Creates a SquareClient using an access token from the environment and the Production environment.

```typescript
import { SquareClient, SquareEnvironment } from "square";

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

--------------------------------

### Get Loyalty Program by ID

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a specific loyalty program by its program ID or the keyword 'main'. Use this endpoint to get details of a single loyalty program.

```typescript
await client.loyalty.programs.get({
    programId: "program_id"
});
```

--------------------------------

### client.payments.cancelByIdempotencyKey

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Cancels (voids) a payment identified by the idempotency key that is specified in the request. Use this method when the status of a `CreatePayment` request is unknown (for example, after you send a `CreatePayment` request, a network error occurs and you do not get a response). In this case, you can direct Square to cancel the payment using this endpoint. In the request, you provide the same idempotency key that you provided in your `CreatePayment` request that you want to cancel. After canceling the payment, you can submit your `CreatePayment` request again. Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint returns successfully.

```APIDOC
## client.payments.cancelByIdempotencyKey

### Description
Cancels (voids) a payment identified by the idempotency key that is specified in the request. Use this method when the status of a `CreatePayment` request is unknown (for example, after you send a `CreatePayment` request, a network error occurs and you do not get a response). In this case, you can direct Square to cancel the payment using this endpoint. In the request, you provide the same idempotency key that you provided in your `CreatePayment` request that you want to cancel. After canceling the payment, you can submit your `CreatePayment` request again. Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint returns successfully.

### Method
cancelByIdempotencyKey

### Endpoint
client.payments.cancelByIdempotencyKey

### Parameters
#### Request Parameters
- **request** (`Square.CancelPaymentByIdempotencyKeyRequest`) - Required - The request parameters for canceling a payment by idempotency key.
- **requestOptions** (`PaymentsClient.RequestOptions`) - Optional - Options for the request.

### Request Example
```typescript
await client.payments.cancelByIdempotencyKey({
    idempotencyKey: "a7e36d40-d24b-11e8-b568-0800200c9a66"
});
```

### Response
#### Success Response
- Returns a `Square.CancelPaymentByIdempotencyKeyResponse` object.

#### Response Example
```typescript
const response = await client.payments.cancelByIdempotencyKey({
    idempotencyKey: "a7e36d40-d24b-11e8-b568-0800200c9a66"
});
```
```

--------------------------------

### Get WageSetting for a team member

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a WageSetting object for a team member specified by TeamMember.id. Square recommends using RetrieveTeamMember or SearchTeamMembers to get this information directly from the TeamMember.wage_setting field.

```typescript
await client.teamMembers.wageSetting.get({
    teamMemberId: "team_member_id"
});

```

--------------------------------

### client.loyalty.programs.promotions.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a loyalty promotion for a loyalty program.

```APIDOC
## client.loyalty.programs.promotions.create

### Description
Creates a loyalty promotion for a loyalty program. A loyalty promotion enables buyers to earn points in addition to those earned from the base loyalty program. This endpoint sets the loyalty promotion to the `ACTIVE` or `SCHEDULED` status, depending on the `available_time` setting. A loyalty program can have a maximum of 10 loyalty promotions with an `ACTIVE` or `SCHEDULED` status.

### Method
POST

### Endpoint
/loyalty/programs/{program_id}/promotions

### Parameters
#### Path Parameters
- **programId** (string) - Required - The ID of the loyalty program.

#### Request Body
- **loyaltyPromotion** (LoyaltyPromotion) - Required - The loyalty promotion to create.
  - **name** (string) - Required - The name of the promotion.
  - **incentive** (LoyaltyPromotionIncentive) - Required - The incentive for the promotion.
    - **type** (string) - Required - The type of incentive (e.g., POINTS_MULTIPLIER).
    - **pointsMultiplierData** (object) - Optional - Data for points multiplier incentive.
      - **multiplier** (string) - Required - The multiplier value.
  - **availableTime** (LoyaltyPromotionAvailableTimeData) - Required - The time periods when the promotion is active.
    - **timePeriods** (string[]) - Required - The time periods in iCalendar format.
  - **triggerLimit** (LoyaltyPromotionTriggerLimit) - Optional - The limit on how many times the promotion can be triggered.
    - **times** (integer) - Required - The maximum number of times.
    - **interval** (string) - Required - The interval (e.g., DAY).
  - **minimumSpendAmountMoney** (Money) - Optional - The minimum spend required to qualify.
    - **amount** (bigint) - Required - The amount in the smallest currency unit.
    - **currency** (string) - Required - The currency code.
  - **qualifyingCategoryIds** (string[]) - Optional - The IDs of the categories that qualify.
- **idempotencyKey** (string) - Required - A unique string that identifies this `CreateLoyaltyPromotion` request.

### Request Example
```typescript
await client.loyalty.programs.promotions.create({
    programId: "program_id",
    loyaltyPromotion: {
        name: "Tuesday Happy Hour Promo",
        incentive: {
            type: "POINTS_MULTIPLIER",
            pointsMultiplierData: {
                multiplier: "3.0"
            }
        },
        availableTime: {
            timePeriods: ["BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"]
        },
        triggerLimit: {
            times: 1,
            interval: "DAY"
        },
        minimumSpendAmountMoney: {
            amount: BigInt("2000"),
            currency: "USD"
        },
        qualifyingCategoryIds: ["XTQPYLR3IIU9C44VRCB3XD12"]
    },
    idempotencyKey: "ec78c477-b1c3-4899-a209-a4e71337c996"
});
```

### Response
#### Success Response (200)
- **loyaltyPromotion** (LoyaltyPromotion) - The created loyalty promotion.

#### Response Example
```json
{
  "loyaltyPromotion": {}
}
```
```

--------------------------------

### Deprecated batch get inventory counts

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Calls the deprecated batch get counts endpoint to retrieve inventory counts for specified catalog objects and locations, optionally filtered by updatedAfter.

```typescript
await client.inventory.deprecatedBatchGetCounts({
    catalogObjectIds: ["W62UWFY35CWMYGVWK6TWJDNI"],
    locationIds: ["59TNP9SA8VGDA"],
    updatedAfter: "2016-11-16T00:00:00.000Z"
});
```

--------------------------------

### create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a Terminal action request and sends it to the specified device.

```APIDOC
## create

### Description
Creates a Terminal action request and sends it to the specified device.

### Method
create

### Endpoint
client.terminal.actions.create

### Parameters
- **request** (`Square.terminal.CreateTerminalActionRequest`) - Required - The request object containing the idempotency key and action details.
- **requestOptions** (`ActionsClient.RequestOptions`) - Optional - Additional request options.

### Request Example
```typescript
await client.terminal.actions.create({
    idempotencyKey: "thahn-70e75c10-47f7-4ab6-88cc-aaa4076d065e",
    action: {
        deviceId: "{{DEVICE_ID}}",
        deadlineDuration: "PT5M",
        type: "SAVE_CARD",
        saveCardOptions: {
            customerId: "{{CUSTOMER_ID}}",
            referenceId: "user-id-1"
        }
    }
});
```

### Response
Returns `Square.CreateTerminalActionResponse`.
```

--------------------------------

### get

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a specific merchant by its ID.

```APIDOC
## get

### Description
Retrieves the `Merchant` object for the given `merchant_id`.

### Method
GET

### Endpoint
/merchants/{merchantId}

### Parameters
#### Path Parameters
- **merchantId** (string) - Required - The ID of the merchant to retrieve.

### Request Example
```json
{
  "merchantId": "merchant_id"
}
```

### Response
#### Success Response (200)
- **merchant** (object) - The merchant object.

#### Response Example
```json
{
  "merchant": {}
}
```
```

--------------------------------

### Configure SquareClient with Production Environment

Source: https://github.com/square/square-nodejs-sdk/blob/master/README.md

Use SquareEnvironment.Production to set the SDK to use the production API environment. The client is instantiated with the environment option.

```typescript
import { SquareClient, SquareEnvironment } from "square";

const client = new SquareClient({
    environment: SquareEnvironment.Production,
});
```

--------------------------------

### GET /v2/bookings/{bookingId}

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a booking.

```APIDOC
## GET /v2/bookings/{bookingId}

### Description
Retrieves a booking.

To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.
To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.

### Method
GET

### Endpoint
/v2/bookings/{bookingId}

### Parameters
#### Path Parameters
- **bookingId** (string) - Required - The ID of the booking.

#### Query Parameters
- **request** (Square.GetBookingsRequest) - Optional - The request object.
- **requestOptions** (BookingsClient.RequestOptions) - Optional - Request options.

### Request Example
```typescript
await client.bookings.get({
    bookingId: "booking_id"
});
```

### Response
#### Success Response (200)
- **response** (Square.GetBookingResponse) - The response object.

#### Response Example
```json
{}
```
```

--------------------------------

### Custom logger with winston

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/logging.md

Shows how to use a custom logger (e.g., winston) by implementing the `ILogger` interface and passing it to the client's `logging` config.

```ts
import { SquareClient, logging } from "square";
import winston from "winston";

const winstonLogger = winston.createLogger({ level: "debug" });

const logger: logging.ILogger = {
    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
    info: (msg, ...args) => winstonLogger.info(msg, ...args),
    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
    error: (msg, ...args) => winstonLogger.error(msg, ...args),
};

const client = new SquareClient({
    token: "YOUR_TOKEN",
    logging: { logger, silent: false },
});
```

--------------------------------

### GET /v2/webhooks/subscriptions

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/endpoints.md

Lists all webhook subscriptions.

```APIDOC
## GET /v2/webhooks/subscriptions

### Description
Lists all webhook subscriptions.

### Method
GET

### Endpoint
/v2/webhooks/subscriptions

### Response
#### Success Response (200)
- **subscriptions** (WebhookSubscription[]) - List of subscriptions.

#### Response Example
{
  "subscriptions": [
    {
      "id": "subscription_id",
      "name": "My Subscription"
    }
  ]
}

### Authentication
Bearer token.
```

--------------------------------

### Create Loyalty Account with client.loyalty.accounts.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a loyalty account. Requires a `program_id` and a `mapping` with the buyer's `phone_number`. The `idempotencyKey` is required for the request.

```typescript
await client.loyalty.accounts.create({
    loyaltyAccount: {
        programId: "d619f755-2d17-41f3-990d-c04ecedd64dd",
        mapping: {
            phoneNumber: "+14155551234"
        }
    },
    idempotencyKey: "ec78c477-b1c3-4899-a209-a4e71337c996"
});
```

--------------------------------

### Deprecated batch get inventory changes

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Calls the deprecated batch get changes endpoint to retrieve historical inventory changes. Filters by catalog object IDs, location IDs, types, states, and updated time range.

```typescript
await client.inventory.deprecatedBatchGetChanges({
    catalogObjectIds: ["W62UWFY35CWMYGVWK6TWJDNI"],
    locationIds: ["C6W5YS5QM06F5"],
    types: ["PHYSICAL_COUNT"],
    states: ["IN_STOCK"],
    updatedAfter: "2016-11-01T00:00:00.000Z",
    updatedBefore: "2016-12-01T00:00:00.000Z"
});
```

--------------------------------

### client.customers.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a new customer for a business. Requires at least one of the specified fields.

```APIDOC
## client.customers.create

### Description
Creates a new customer for a business. You must provide at least one of the following values in your request: `given_name`, `family_name`, `company_name`, `email_address`, or `phone_number`.

### Method
POST

### Endpoint
/customers

### Parameters
#### Request Body
- **givenName** (string) - Optional - The given name of the customer.
- **familyName** (string) - Optional - The family name of the customer.
- **emailAddress** (string) - Optional - The email address of the customer.
- **address** (object) - Optional - The address of the customer. Contains fields such as `addressLine1`, `addressLine2`, `locality`, `administrativeDistrictLevel1`, `postalCode`, and `country`.
- **phoneNumber** (string) - Optional - The phone number of the customer.
- **referenceId** (string) - Optional - A reference ID for the customer.
- **note** (string) - Optional - A note about the customer.

### Request Example
```typescript
await client.customers.create({
    givenName: "Amelia",
    familyName: "Earhart",
    emailAddress: "Amelia.Earhart@example.com",
    address: {
        addressLine1: "500 Electric Ave",
        addressLine2: "Suite 600",
        locality: "New York",
        administrativeDistrictLevel1: "NY",
        postalCode: "10003",
        country: "US"
    },
    phoneNumber: "+1-212-555-4240",
    referenceId: "YOUR_REFERENCE_ID",
    note: "a customer"
});
```

### Response
#### Success Response (200)
Returns a `Square.CreateCustomerResponse` containing the created customer.

#### Response Example
```typescript
// The response contains the created customer object.
```
```

--------------------------------

### Get snippet with client.snippets.get()

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves the snippet added by your application from a Square Online site. A site can contain snippets from multiple applications, but only your own snippet is returned. Use ListSites to get site IDs. Square Online APIs are in early access.

```typescript
await client.snippets.get({
    siteId: "site_id"
});
```

--------------------------------

### GET /v2/team-members/jobs/{job_id}

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a specified job.

```APIDOC
## [GET] /v2/team-members/jobs/{job_id}

### Description
Retrieves a specified job.

### Method
GET

### Endpoint
/v2/team-members/jobs/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the job to retrieve.

### Request Example
```typescript
await client.team.retrieveJob({
    jobId: "job_id"
});
```

### Response
#### Success Response (200)
- **job** (object) - The requested job.
- **errors** (array) - Any errors that occurred during the request.

#### Response Example
```json
{
  "job": {
    "job_id": "string",
    "title": "string",
    "is_tip_eligible": true,
    "created_at": "string",
    "updated_at": "string"
  },
  "errors": []
}
```
```

--------------------------------

### Get transaction details

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves details for a single transaction.

```typescript
await client.locations.transactions.get({
    locationId: "location_id",
    transactionId: "transaction_id"
});
```

--------------------------------

### Create customer card with client.customers.cards.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Adds a card on file to an existing customer. Calls are idempotent; multiple calls with the same card nonce return the same card record created during the first call.

```typescript
await client.customers.cards.create({
    customerId: "customer_id",
    cardNonce: "YOUR_CARD_NONCE",
    billingAddress: {
        addressLine1: "500 Electric Ave",
        addressLine2: "Suite 600",
        locality: "New York",
        administrativeDistrictLevel1: "NY",
        postalCode: "10003",
        country: "US"
    },
    cardholderName: "Amelia Earhart"
});
```

--------------------------------

### GET /v2/labor/shifts/{id}

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a single Shift by its ID.

```APIDOC
## [GET] /v2/labor/shifts/{id}

### Description
Returns a single `Shift` specified by `id`.

### Method
GET

### Endpoint
/v2/labor/shifts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the shift to retrieve.

### Request Example
```json
{
  "id": "id"
}
```

### Response
#### Success Response (200)
- **shift** (object) - The requested `Shift`.

#### Response Example
```json
{
  "shift": {}
}
```
```

--------------------------------

### Run the test suite with yarn

Source: https://github.com/square/square-nodejs-sdk/blob/master/CONTRIBUTING.md

Runs the full test suite using the yarn test command.

```bash
yarn test
```

--------------------------------

### GET /v2/devices/codes/{id}

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves DeviceCode with the associated ID.

```APIDOC
## GET /v2/devices/codes/{id}

### Description
Retrieves DeviceCode with the associated ID.

### Method
GET

### Endpoint
/v2/devices/codes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the device code.

### Request Example
```typescript
await client.devices.codes.get({
    id: "id"
});
```

### Response
#### Success Response (200)
- **device_code** (object) - The requested device code.
- **errors** (array) - Any errors that occurred during the request.

#### Response Example
```json
{
  "device_code": {},
  "errors": []
}
```
```

--------------------------------

### Create a location with client.locations.create()

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a new location with a unique name and address. The location persists forever and is visible to the seller for management.

```typescript
await client.locations.create({
    location: {
        name: "Midtown",
        address: {
            addressLine1: "1234 Peachtree St. NE",
            locality: "Atlanta",
            administrativeDistrictLevel1: "GA",
            postalCode: "30309"
        },
        description: "Midtown Atlanta store"
    }
});
```

--------------------------------

### GET /v2/customers/groups

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves the list of customer groups of a business.

```APIDOC
## GET /v2/customers/groups

### Description
Retrieves the list of customer groups of a business.

### Method
GET

### Endpoint
/v2/customers/groups

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - A pagination cursor returned by a previous call to this endpoint.
- **limit** (integer) - Optional - The maximum number of results to return per page.

### Request Example
```json
{
  "cursor": "cursor",
  "limit": 1
}
```

### Response
#### Success Response (200)
- **groups** (array) - The list of customer groups.
- **cursor** (string) - A pagination cursor for the next page.

#### Response Example
```json
{
  "groups": [
    {
      "id": "group_id",
      "name": "Loyal Customers"
    }
  ],
  "cursor": "next_cursor"
}
```
```

--------------------------------

### Create bank account with client.bankAccounts.createBankAccount

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Stores a bank account on file for a Square account. Requires an idempotency key, a source ID, and a customer ID.

```typescript
await client.bankAccounts.createBankAccount({
    idempotencyKey: "4e43559a-f0fd-47d3-9da2-7ea1f97d94be",
    sourceId: "bnon:CA4SEHsQwr0rx6DbWLD5BQaqMnoYAQ",
    customerId: "HM3B2D5JKGZ69359BTEHXM2V8M"
});
```

--------------------------------

### GET /v2/subscriptions/{subscription_id}

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a specific subscription by its ID.

```APIDOC
## GET /v2/subscriptions/{subscription_id}

### Description
Retrieves a specific subscription.

### Method
GET

### Endpoint
/v2/subscriptions/{subscription_id}

### Parameters
#### Path Parameters
- **subscriptionId** (string) - Required - The ID of the subscription to retrieve.

#### Query Parameters
- **include** (string) - Optional - A comma-separated list of related objects to include in the response.

### Request Example
```
GET /v2/subscriptions/subscription_id?include=include
```

### Response
#### Success Response (200)
- **subscription** (object) - The requested subscription.

#### Response Example
```json
{
  "subscription": {}
}
```
```

--------------------------------

### Get an order by ID with client.orders.get

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves an order by its ID.

```typescript
await client.orders.get({
    orderId: "order_id"
});
```

--------------------------------

### List loyalty promotions with client.loyalty.programs.promotions.list

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Lists loyalty promotions for a program, sorted by created_at descending. Shows three iteration patterns: async iteration, manual page-by-page navigation, and accessing the underlying response.

```typescript
const pageableResponse = await client.loyalty.programs.promotions.list({
    programId: "program_id",
    status: "ACTIVE",
    cursor: "cursor",
    limit: 1
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.loyalty.programs.promotions.list({
    programId: "program_id",
    status: "ACTIVE",
    cursor: "cursor",
    limit: 1
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;
```

--------------------------------

### client.bookings.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a new booking with required fields. Requires appropriate OAuth scopes and subscription for seller-level calls.

```APIDOC
## client.bookings.create

### Description
Creates a booking. The required input must include the following: `Booking.location_id`, `Booking.start_at`, `Booking.AppointmentSegment.team_member_id`, `Booking.AppointmentSegment.service_variation_id`, `Booking.AppointmentSegment.service_variation_version`. To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope. To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope. For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus* or *Appointments Premium*.

### Method
create

### Endpoint
client.bookings.create

### Parameters
#### Request Parameters
- **request** (`Square.CreateBookingRequest`) - Required - The request object containing booking details.
- **requestOptions** (`BookingsClient.RequestOptions`) - Optional - Additional request options.

### Request Example
```typescript
await client.bookings.create({
    booking: {}
});
```

### Response
#### Success Response
- Returns `Square.CreateBookingResponse` - The created booking response.

#### Response Example
```typescript
// The response is a Square.CreateBookingResponse object.
```
```

--------------------------------

### GET /v2/employees/{id}

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a specific employee by ID.

```APIDOC
## [GET] /v2/employees/{id}

### Description
Retrieves a specific employee by ID.

### Method
GET

### Endpoint
/v2/employees/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the employee to retrieve.

### Request Example
{
  "id": "id"
}

### Response
#### Success Response (200)
- **employee** (object) - The employee object.

#### Response Example
{
  "employee": {}
}
```

--------------------------------

### Get employee by ID

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a single employee by ID.

```typescript
await client.employees.get({
    id: "id"
});
```

--------------------------------

### Create loyalty promotion with client.loyalty.programs.promotions.create

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Creates a loyalty promotion with a points multiplier incentive, available time, trigger limit, minimum spend, and qualifying categories. Sets the promotion to ACTIVE or SCHEDULED based on available_time; a program can have at most 10 ACTIVE or SCHEDULED promotions.

```typescript
await client.loyalty.programs.promotions.create({
    programId: "program_id",
    loyaltyPromotion: {
        name: "Tuesday Happy Hour Promo",
        incentive: {
            type: "POINTS_MULTIPLIER",
            pointsMultiplierData: {
                multiplier: "3.0"
            }
        },
        availableTime: {
            timePeriods: ["BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"]
        },
        triggerLimit: {
            times: 1,
            interval: "DAY"
        },
        minimumSpendAmountMoney: {
            amount: BigInt("2000"),
            currency: "USD"
        },
        qualifyingCategoryIds: ["XTQPYLR3IIU9C44VRCB3XD12"]
    },
    idempotencyKey: "ec78c477-b1c3-4899-a209-a4e71337c996"
});
```

--------------------------------

### List sites with client.sites.list()

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Lists the Square Online sites that belong to a seller. Sites are listed in descending order by the `created_at` date. Square Online APIs are in early access.

```typescript
await client.sites.list();
```

--------------------------------

### GET /v2/bookings/business-profile

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a seller's booking profile.

```APIDOC
## GET /v2/bookings/business-profile

### Description
Retrieves a seller's booking profile.

### Method
GET

### Endpoint
/v2/bookings/business-profile

### Parameters
#### Query Parameters
- **requestOptions** (BookingsClient.RequestOptions) - Optional - Request options.

### Request Example
```typescript
await client.bookings.getBusinessProfile();
```

### Response
#### Success Response (200)
- **response** (Square.GetBusinessBookingProfileResponse) - The response object.

#### Response Example
```json
{}
```
```

--------------------------------

### get

Source: https://github.com/square/square-nodejs-sdk/blob/master/_autodocs/api-reference/payments-client.md

Retrieves details of a specific payment by its payment ID.

```APIDOC
## `get`

### Description
Retrieves details of a specific payment by its payment ID.

### Method
GET

### Endpoint
/payments/{paymentId}

### Parameters
#### Path Parameters
- **paymentId** (string) - Required - The unique ID of the payment to retrieve.

### Request Example
```ts
const { payment } = await client.payments.get({ paymentId: "ptest:..." });
if (!payment) throw new Error("Payment not found");
```

### Response
#### Success Response (200)
- **errors** (Square.Error[]) - Optional - Any errors that occurred during the request.
- **payment** (Square.Payment) - Optional - The requested payment.

#### Response Example
```json
{
  "payment": {}
}
```
```

--------------------------------

### Get Loyalty Account with client.loyalty.accounts.get

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a loyalty account by its `accountId`.

```typescript
await client.loyalty.accounts.get({
    accountId: "account_id"
});
```

--------------------------------

### Get a refund with client.refunds.get

Source: https://github.com/square/square-nodejs-sdk/blob/master/reference.md

Retrieves a specific refund using the `refund_id`.

```typescript
await client.refunds.get({
    refundId: "refund_id"
});

```
Tokens:
Raw