> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Square plugin

> Square's commerce API. Take and refund payments, create orders, payment links and invoices, manage customers, cards, disputes, catalog and inventory, and read locations and merchant settings, in the Square sandbox or in production.

Use **Square** through Corsair: one client, typed API calls.

Authentication is a Square access token, sent as a Bearer token: a personal access token or an OAuth token. An OAuth token is refreshed when it expires, and once more after Square answers a request with a 401; a missing token fails with a clear error instead of an empty Bearer. Square runs production and a sandbox as separate worlds, and a token only works in the one it came from. The plugin calls production by default; pass `square({ environment: 'sandbox' })` to call `connect.squareupsandbox.com` with a sandbox token. Every request sends `Square-Version: 2026-09-16`. Inputs and answers use Square's own snake\_case field names, and a money amount is `{ amount, currency }` with the amount in the currency's smallest unit (cents for USD).

**Idempotency.** Calls that create or change money, or that Square lets you repeat safely, take an `idempotency_key`: nine operations require one (`payments.create`, `payments.update`, `payments.refund`, `payments.cancelByIdempotencyKey`, `orders.pay`, `cards.create`, `catalog.upsert`, `disputes.createEvidenceText` and `disputes.createEvidenceFile`), and many more accept one. Input keys a schema does not list are dropped, so a misspelled optional `idempotency_key` (for example `idempotencyKey`) sends the call without a key: it is then not deduplicated and not retried after a server error. You supply the key; the plugin sends it unchanged and never makes one up. Reuse the same key to retry the same call: Square then returns the first result instead of acting twice, so a timed-out charge cannot charge a card twice. A new key is a new payment. If the response to `payments.create` was lost and you cannot tell whether it ran, `payments.cancelByIdempotencyKey` voids it by the same key.

**Operations that move money:** `payments.create`, `payments.update`, `payments.complete`, `payments.cancel`, `payments.cancelByIdempotencyKey`, `payments.refund`, `orders.pay`, `invoices.publish` (it may charge the card on file) and `disputes.accept`. Their descriptions say so. `payments.refund`, `payments.cancel`, `payments.cancelByIdempotencyKey` and `disputes.accept` cannot be undone. Every operation that moves money is `destructive`, as are `webhookSubscriptions.test` (it sends an event to your URL), `invoices.update`, `invoices.createAttachment` and `invoices.deleteAttachment` (Square emails or texts the customer when the invoice's `delivery_method` is `EMAIL` or `SMS`) and the deletes, so a permission policy can hold them for approval.

**Retries.** A 429 is retried by Corsair's HTTP layer, up to three times, waiting for `Retry-After` when Square sends one: Square rejected the request without running it, so this holds for every operation. After a 5xx or a dropped connection the first attempt may have run, so the plugin retries (twice, with backoff) only reads, including the read-only `POST` searches, and the nine operations that require an `idempotency_key`, with the same key. Every other write, including a `PUT`, a `DELETE` and a call whose optional key you passed, is not retried: check its state with a read before you repeat it, with the same key if it took one. A declined card (`PAYMENT_METHOD_ERROR`) is Square's answer and is never retried.

**Errors.** A failed call throws Corsair's `ApiError` unchanged, with `status`, `retryAfter` and Square's response as `body`. Its message is the HTTP status text; Square's `errors[]` (`category`, `code`, `detail`, `field`) is in `error.body.errors`, and `squareErrors(error)` from `@corsair-dev/square` returns it typed. A call that got no response throws `SquareNetworkError`; its message and `cause` carry only the error name and system code (for example `TypeError ECONNRESET`), never the original text, which can quote the `Authorization` header. A token with a line break or control character is refused before anything is sent.

**Pagination.** List and search operations take `cursor` and `limit` and return the next `cursor`; pass it back for the next page. It goes in the query string for `GET` lists and in the body for the `POST` searches.

**Files.** `disputes.createEvidenceFile` and `invoices.createAttachment` take the file as base64 in `file_base64`, with an optional `filename` (default: `attachment` plus the extension of its type); the plugin sends it to Square as multipart.

**Not included yet:** Square's GraphQL endpoint, webhook triggers, and the other API families (bookings beyond the business profile, loyalty, gift cards, payouts, team, labor, terminal, subscriptions).

**What you get:**

* 123 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/square better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/square better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/square better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/square better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { square } from '@corsair-dev/square';

export const corsair = createCorsair({
	plugins: [
		square(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the Square API key before the first call: `pnpm corsair setup --plugin=square --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> square()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

> [tab] OAuth 2.0
>
> Open [hub.corsair.dev](https://hub.corsair.dev/dashboard), navigate to your project, and enter the **client ID** and **client secret** from your Square OAuth app.
>
> ```ts theme={null}
> square({
> 	authType: 'oauth_2',
> })
> ```
>
> More: [OAuth 2.0](https://docs.corsair.dev/concepts/oauth)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'square',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List the seller's locations**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.square.api.locations.list({});
```

**Create a customer**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.square.api.customers.create({ given_name: 'Ada', family_name: 'Lovelace', email_address: 'ada@example.com' });
```

See the full list on the [API](https://docs.corsair.dev/plugins/square/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/square/api.md)
>
> Every `square.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.