> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/square.md).

# Square

## OAuth app properties

| Property                | Value                                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Multi-tenant**        | **Yes.** Any Square seller can authorize one production app.                                                          |
| **Vendor review**       | **None.** Production credentials work as soon as the app exists. A listing in the Square App Marketplace is optional. |
| **Review time**         | Not applicable.                                                                                                       |
| **Users before review** | No limit.                                                                                                             |
| **App owner**           | Any Square developer account.                                                                                         |
| **Regions**             | One production app for all sellers. The Sandbox has its own application ID and secret.                                |
| **Client secret**       | No expiry documented.                                                                                                 |
| **Rate limits**         | Not published. Square answers `429` with `RATE_LIMITED` when an app sends too many requests in a short time.          |
| **Checked**             | 2026-11-13                                                                                                            |

**Limitations**

* One Appmixer configuration connects to either the Sandbox or production, depending on its `environment` setting. Sandbox credentials do not work in production.
* An access token expires after 30 days. Appmixer refreshes it; the refresh token of the code flow does not expire. A connected account stops working only when the seller revokes the app.
* The connector asks for `MERCHANT_PROFILE_READ`, `CUSTOMERS_READ`, `CUSTOMERS_WRITE`, `ORDERS_READ`, `ORDERS_WRITE`, `ITEMS_READ` and `INVENTORY_READ`. Other endpoints, for example payments, answer `INSUFFICIENT_SCOPES` in **Make API Call**.

Sources: [OAuth overview](https://developer.squareup.com/docs/oauth-api/overview), [Move OAuth to production](https://developer.squareup.com/docs/oauth-api/movetoprod), [Refresh, revoke and limit the scope of OAuth tokens](https://developer.squareup.com/docs/oauth-api/refresh-revoke-limit-scope). What the rows mean: [OAuth app properties](https://docs.appmixer.com/connector-configuration/oauth-app-properties.md).

## Square – Connector Configuration

### Step 1: Create a Square Developer Account & Access Developer Portal

* Sign in to your Square account at [Square](https://squareup.com/)
* Navigate to the [Square Developer Portal](https://developer.squareup.com/)
* Create a developer account if you don't have one already

> ⚠️ **Note**: You need a Square business account to access production features. Sandbox is available for development.

***

### Step 2: Create Your Application

1. **Create a new application**:
   * Go to [Developer Dashboard](https://developer.squareup.com/apps)
   * Click **"Create your first application"** or **"+"** to add a new app
   * Fill in the application details:
     * **Application Name** (e.g., "My Payment Integration")
     * **Application Description** - Describe your integration's purpose
2. **Choose Environment**:
   * **Sandbox** - For development and testing
   * **Production** - For live transactions with real money

***

### Step 3: Configure OAuth Settings

1. **Navigate to OAuth Tab**:
   * In your application dashboard, click on **"OAuth"**
   * Configure OAuth settings for secure authentication
2. **Set Redirect URIs**:
   * Add your callback URL in the **"Redirect URL"** field
   * For Appmixer, set the redirect URI to:

```http
https://[YOUR_API_BASE]/auth/square/callback
```

Example:

```http
https://api.appmixer.com/auth/square/callback
```

3. **Configure Permissions**:
   * Select the Square API permissions your app needs:
     * `PAYMENTS_READ` - Read payment information
     * `PAYMENTS_WRITE` - Process payments
     * `ORDERS_READ` - Read order information
     * `ORDERS_WRITE` - Create and update orders
     * `CUSTOMERS_READ` - Read customer profiles
     * `CUSTOMERS_WRITE` - Create and update customers
     * `INVENTORY_READ` - Read inventory information
     * `ITEMS_READ` - Read catalog items

***

### Step 4: Copy Your Credentials

After configuring your application, you'll find your API credentials:

* **Application ID** - Your OAuth application identifier
* **Application Secret** - Your OAuth application secret
* **Access Token** - For server-to-server API calls (if using personal access token)

⚠️ **Important**: Keep your Application Secret secure and never expose it in client-side code!

***

### Step 5: Webhook Configuration (Optional)

If your integration needs real-time updates:

1. **Navigate to Webhooks**:
   * In your application dashboard, click on **"Webhooks"**
   * Click **"Add Endpoint"**
2. **Configure Webhook Settings**:
   * **Notification URL**: Your endpoint to receive webhook notifications
   * **Events**: Select events you want to subscribe to:
     * `payment.created`
     * `payment.updated`
     * `order.created`
     * `order.updated`
     * `customer.created`
     * `customer.updated`
3. **Webhook Security**:
   * Square signs webhook requests with a signature
   * Use the provided webhook signature key to verify authenticity

***

1. **Test OAuth Flow**:
   * Use your Application ID to initiate OAuth authorization
   * Square authorization URL: `https://connect.squareup.com/oauth2/authorize`
   * Required parameters: `client_id`, `redirect_uri`, `response_type=code`, `scope`
2. **API Testing**:
   * Square API base URLs:
     * **Sandbox**: `https://connect.squareupsandbox.com/`
     * **Production**: `https://connect.squareup.com/`
   * Include `Authorization: Bearer <access_token>` header in requests
   * Test with endpoints like `/v2/locations` to verify authentication

***

### Step 6: Rate Limits

**Rate Limits**:

* **API calls**: 10 requests per second per access token
* **Webhooks**: No specific rate limits, but implement proper handling
* **Payment processing**: Additional limits may apply based on your Square account

***

### Useful Links

* [Square Developer Documentation](https://developer.squareup.com/)
* [API Reference](https://developer.squareup.com/reference/square)
* [OAuth Guide](https://developer.squareup.com/docs/oauth-api/overview)
* [Webhook Documentation](https://developer.squareup.com/docs/webhooks/overview)
* [Rate Limits](https://developer.squareup.com/docs/build-basics/api-lifecycle#rate-limiting)
* [Sandbox Testing](https://developer.squareup.com/docs/testing/sandbox)

***

## Backoffice configuration

Configuration ID: `appmixer:square` (Backoffice → Configuration; see [Connector Configuration](https://docs.appmixer.com/getting-started/services) for how a configuration is created and how its keys reach the connector).

* `clientId` — The Application ID of the Square application. Not needed when Square is authenticated through the Appmixer Auth Hub.
* `clientSecret` — The Application Secret of the same application. Not needed with the Auth Hub.
* `environment` — Optional. `production` (default) uses `connect.squareup.com`; any other value, for example `sandbox`, uses the sandbox `connect.squareupsandbox.com` for the OAuth flow and the API calls. Set it to `sandbox` when `clientId` and `clientSecret` are the Sandbox credentials.
* `outputFilePrefix` — Optional. File name prefix of the CSV file that **Find Customers** and **List Customer Groups** create when their output is set to a file. Default `square-objects-export`.

<figure><img src="https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-762ae3fa23de64b0901e915c628bda29a0e07073%2Fsquare.png?alt=media" alt="Square configuration in the Backoffice"><figcaption><p>The screenshot shows the ID <code>acme:square</code>; use <code>appmixer:square</code>.</p></figcaption></figure>

The same keys can be set with the CLI (`-u` updates the existing configuration instead of creating it):

```bash
appmixer service-config set appmixer:square -u -d '{
  "clientId": "<application id>",
  "clientSecret": "<application secret>"
}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/square.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
