ioLoop Docs

Appearance

$io.square ​

Server API reference.

Functions ​

$io.square.directApiCall ​

Call any Square HTTP REST endpoint directly using raw path and method.

Usage ​

js
$io.square.directApiCall(connectionName, path, method, queryParams, body)

Description ​

This function sends a direct HTTP request to the Square REST API using a specified path and method. Authentication is handled automatically using the OAuth2 token associated with the given connection.

This is useful for calling endpoints that are not covered by the Square Node.js SDK or when precise HTTP-level control is required.

⚠️ Parameters such as method, queryParams, and body must conform to the requirements of the target endpoint as documented in the official Square API reference: https://developer.squareup.com/reference/square

Examples:

js
$io.square.directApiCall("myConn", "/v2/customers", "GET")
$io.square.directApiCall("myConn", "/v2/customers", "POST", null, {
    given_name: "Alice",
    family_name: "Johnson",
    email_address: "[email protected]"
})

NOTE: that all payment amounts are in the smallest denomination of the currency — usually:

  • Cents for USD (so 100 = $1.00)
  • Pence for GBP (so 100 = £1.00)
  • Yen for JPY (no decimal, so 100 = ¥100)

Usage Scenarios ​

  • Access Square API endpoints not exposed in the Node.js SDK
  • Test new or undocumented Square REST endpoints
  • Perform raw HTTP operations against Square's REST API

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Square OAuth connection (as configured in ioLoop).

path ​

Type: String

Required: Yes

The REST API path to call (e.g., '/v2/payments', '/v2/customers/ABC'). Must begin with '/'.

method ​

Type: String

Required: Yes

The HTTP method to use (e.g., 'GET', 'POST', 'PUT', 'DELETE'). Must match the Square API specification for the given path.

queryParams ​

Type: Object

Required: No

Optional. An object representing query string parameters as required by the Square endpoint.

body ​

Type: Object

Required: No

Optional. The request body to send (for POST, PUT, etc). Must match the structure expected by the target Square endpoint.

Output ​

Type: Promise

Returns a Promise resolving to:

  • status: true if the HTTP status is 2xx, false otherwise
  • data: the parsed JSON response returned by Square
  • err: a descriptive error message or the response body from Square in case of failure

$io.square.execSdk ​

Execute any Square SDK method (v40+ Node.js SDK) dynamically using resource and operation names.

Usage ​

js
$io.square.execSdk(connectionName, resourceType, operation, args)

Description ​

This function provides low-level access to any Square SDK resource using the official Square Node.js SDK (v40+). It dynamically routes the request through the authenticated Square connection and invokes the specified operation on the given resource with the provided arguments.

This approach gives you complete access to all Square resources exposed via the SDK.

For example:

js
$io.square.execSdk("mySquareConn", "payments", "list", [{ sortOrder: "DESC" }])

This is ideal for scenarios where no higher-level wrapper (e.g. $io.square.listPayments) is available yet. NOTE: that all payment amounts are in the smallest denomination of the currency — usually:

  • Cents for USD (so 100 = $1.00)
  • Pence for GBP (so 100 = £1.00)
  • Yen for JPY (no decimal, so 100 = ¥100)

Usage Scenarios ​

  • Access a Square SDK method not yet wrapped by ioLoop directly
  • Experiment with new or less common Square resources

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Square OAuth connection (as configured in ioLoop).

resourceType ​

Type: String

Required: Yes

The Square API resource to access (e.g., 'payments', 'customers', 'orders').

operation ​

Type: String

Required: Yes

The method on the resource to invoke (e.g., 'list', 'create', 'retrieve').

args ​

Type: Array

Required: No

Optional. An array of arguments to pass to the selected Square SDK method. The arguments must be in the same positional order expected by the target method in the Square Node.js SDK (v40+). For example, to call orders.calculateTax(order, options), pass [order, options].

Output ​

Type: Promise

Returns a Promise resolving to an object with:

  • status: true if the operation was successful, false otherwise
  • data: the raw data returned from the Square API (may vary depending on resource/operation)
  • err: error message or Square API error response if the operation failed

$io.square.listPayments ​

List Square payments within a given time range and optional filters.

Usage ​

js
$io.square.listPayments(connectionName, startDateTime, endDateTime, sortOrder, limit, cursor, locationId, other)

Description ​

This function lists payments from the Square API using the authenticated connection. It supports filtering by time range, sort order, pagination (via cursor), and location ID. Additional query parameters supported by Square's payments.list method may be passed via the other object. The result includes flattened, key information about each payment such as amount, card info, and metadata. NOTE: that all payment amounts are in the smallest denomination of the currency — usually:

  • Cents for USD (so 100 = $1.00)
  • Pence for GBP (so 100 = £1.00)
  • Yen for JPY (no decimal, so 100 = ¥100)

Usage Scenarios ​

  • Fetch payments made in a specific time period for analytics or reporting
  • Paginate through historical payments using cursor
  • Filter payments by Square location ID or sort order

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the Square OAuth connection (as configured in ioLoop).

startDateTime ​

Type: String | Date | moment

Required: No

Start of the time range. Defaults to 30 days ago if omitted.

endDateTime ​

Type: String | Date | moment

Required: No

End of the time range. Defaults to current time if omitted.

sortOrder ​

Type: String

Required: No

Optional. ASC or DESC. Default is ASC.

limit ​

Type: Number

Required: No

Optional. Maximum number of results to return (up to Square's limit, typically 100).

cursor ​

Type: String

Required: No

Optional. A pagination cursor returned from a previous call.

locationId ​

Type: String

Required: No

Optional. Filter payments by specific Square location.

other ​

Type: Object

Required: No

Optional. Any additional parameters supported by the Square listPayments API, such as total, cardBrand, etc.

Output ​

Type: Promise

Returns a Promise resolving to an object with:

  • status: true on success, false on error
  • data: if successful, contains:
    • payments: an array of flattened payment objects with fields:
      • id (String): Unique identifier for the payment
      • createdAt (String): ISO 8601 timestamp when the payment was created
      • status (String): Status of the payment (e.g., COMPLETED, CANCELED)
      • sourceType (String): Payment source (e.g., CARD, CASH)
      • amount (Number|String): Primary amount paid (from amountMoney.amount)
      • currency (String): ISO currency code
      • tipAmount (Number|String): Optional tip amount
      • totalAmount (Number|String): Total payment amount including tips and fees
      • appFeeAmount (Number|String): Fee collected by the app (if any)
      • refundedAmount (Number|String): Refunded amount, if applicable
      • cardBrand (String): Card brand (e.g., VISA, MASTERCARD) — if sourceType is CARD
      • last4 (String): Last four digits of card number — if sourceType is CARD
      • entryMethod (String): How the card was entered (e.g., CHIP, MANUAL)
      • orderId (String): Associated Square order ID
      • customerId (String): Linked customer ID
      • locationId (String): Location where the payment was processed
      • receiptUrl (String): Public URL to the payment receipt
      • referenceId (String): Optional external reference ID
      • note (String): Optional note attached to the payment
      • teamMemberId (String): ID of the team member who took the payment
    • cursor: A cursor string for fetching the next page (if available)
  • err: error message if status is false