How to Connect Square to an AI Agent
Auth setup
1. Create app at developer.squareup.com. 2. For testing: use Sandbox Access Token (no real money). 3. For production: generate Personal Access Token in Developer Dashboard. 4. Use as: Authorization: Bearer {token}.
Key facts
| Base URL | https://connect.squareup.com/v2/ |
|---|
| API version | v2 |
|---|
| Auth | OAuth 2.0 or Personal Access Token. For agents, use Personal Access Token (generate in Square Developer Dashboard). Include as Bearer token in Authorization header. |
|---|
| Token URL | https://connect.squareup.com/oauth2/token |
|---|
| Scopes | PAYMENTS_READ,PAYMENTS_WRITE,ORDERS_READ,ITEMS_READ,INVENTORY_READ |
|---|
| Request body | application/json |
|---|
| Pagination | cursor-based: response has 'cursor' field. Pass as query param for next page. |
|---|
| Rate limit | Varies by endpoint. Most: 30 requests/second. Batch endpoints: 10/second. HTTP 429 with Retry-After. |
|---|
| Error format | JSON: {"errors":[{"category":"INVALID_REQUEST_ERROR","code":"NOT_FOUND","detail":"..."}]} |
|---|
Key endpoints
| Method | Path | Description |
|---|
GET | /locations | List store locations (get location_id first) |
POST | /payments | Create a payment (charge a card) |
POST | /orders/search | Search orders by date, status, etc. |
GET | /catalog/list | List product catalog items |
POST | /inventory/changes/batch-create | Batch update inventory counts |
Quickstart
GET /v2/locations HTTP/1.1
Host: connect.squareup.com
Authorization: Bearer {access_token}
Accept: application/json
Response: {"locations":[{"id":"LOC123","name":"渋谷店","address":{"country":"JP"},"currency":"JPY"}]}
Agent pitfalls & tips
- location_id is required for most endpoints — always call GET /locations first (same pattern as freee's company_id).
- Sandbox available with separate base URL (squareupsandbox.com). Test payments without real charges.
- Amounts are in the smallest currency unit. JPY is already integer, so ¥1000 = 1000 (no conversion needed, unlike USD).
- Square in Japan supports IC card payments (Suica, PASMO) and QR code (PayPay). These show as different tender types in the API.
- Idempotency: POST requests require 'Idempotency-Key' header to prevent duplicate charges. Always include it.
- Catalog items have variations (sizes, colors). Access via catalog/search with type filter.
Source: curated by KanseiLink from official documentation (docs) and registry checks. Last reviewed: 2026-04-04. Specs change — verify against the official docs before production use.
Frequently Asked Questions
What is Square's AEO score?
▼
Square has an AEO score of 0.60 and is rated BBB (Basic agent connectivity available). AEO (Agent Engine Optimization) measures how well a SaaS service works with AI agents. Scores range from 0.00 to 1.00, with grades from AAA (best) to D (not agent-ready).
Is Square AI-agent-ready?
▼
Square is currently connectable for AI agent use. API access is available but no dedicated MCP server has been published yet. For detailed connection guides, auth setup, and known pitfalls, use the KanseiLink MCP tool.
How does Square compare to other Payment services?
▼
In the Payment category, Square is rated BBB. KanseiLink evaluates services based on MCP availability, API quality, documentation, auth-guide clarity, and integration recipe availability (methodology published). Visit the full rankings at kansei-link.com to see how Square compares.
How can I integrate Square with an AI agent?
▼
The fastest way to integrate Square with an AI agent is through KanseiLink MCP. Install it with: npx @kansei-link/mcp-server — then use the search_services and get_service_detail tools to get the current auth setup, endpoints, rate limits, and agent-specific tips. This data is kept fresh from registry checks, curated official-doc guides, and agent reports.
How do I authenticate with Square?
▼
OAuth 2.0 or Personal Access Token. For agents, use Personal Access Token (generate in Square Developer Dashboard). Include as Bearer token in Authorization header. Setup: 1. Create app at developer.squareup.com. 2. For testing: use Sandbox Access Token (no real money). 3. For production: generate Personal Access Token in Developer Dashboard. 4. Use as: Authorization: Bearer {token}.
What are Square's API rate limits?
▼
Varies by endpoint. Most: 30 requests/second. Batch endpoints: 10/second. HTTP 429 with Retry-After.