squareupSquare API integration with managed OAuth. Process payments, manage customers, orders, catalog, inventory, and invoices. Use this skill when users want to accept payments, manage point-of-sale operations, track inventory, or handle invoicing through Square. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key.
Install via ClawdBot CLI:
clawdbot install byungkyu/squareupAccess the Square API with managed OAuth authentication. Process payments, manage customers, orders, catalog items, inventory, and invoices.
# List locations
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/squareup/v2/locations')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFhttps://gateway.maton.ai/squareup/{native-api-path}Replace {native-api-path} with the actual Square API endpoint path. The gateway proxies requests to connect.squareup.com and automatically injects your OAuth token.
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEYEnvironment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"Manage your Square OAuth connections at https://ctrl.maton.ai.
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=squareup&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFpython <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'squareup'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFResponse:
{
"connection": {
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "squareup",
"metadata": {}
}
}Open the returned url in a browser to complete OAuth authorization.
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf you have multiple Square connections, specify which one to use with the Maton-Connection header:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/squareup/v2/locations')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf omitted, the gateway uses the default (oldest) active connection.
GET /squareup/v2/locationsGET /squareup/v2/locations/{location_id}POST /squareup/v2/locations
Content-Type: application/json
{
"location": {
"name": "New Location",
"address": {
"address_line_1": "123 Main St",
"locality": "San Francisco",
"administrative_district_level_1": "CA",
"postal_code": "94102",
"country": "US"
}
}
}PUT /squareup/v2/locations/{location_id}
Content-Type: application/json
{
"location": {
"name": "Updated Location Name"
}
}GET /squareup/v2/merchants/meGET /squareup/v2/merchantsGET /squareup/v2/paymentsWith filters:
GET /squareup/v2/payments?location_id={location_id}&begin_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00ZGET /squareup/v2/payments/{payment_id}POST /squareup/v2/payments
Content-Type: application/json
{
"source_id": "cnon:card-nonce-ok",
"idempotency_key": "unique-key-12345",
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"location_id": "{location_id}"
}PUT /squareup/v2/payments/{payment_id}
Content-Type: application/json
{
"payment": {
"tip_money": {
"amount": 200,
"currency": "USD"
}
},
"idempotency_key": "unique-key-67890"
}POST /squareup/v2/payments/{payment_id}/complete
Content-Type: application/json
{}POST /squareup/v2/payments/{payment_id}/cancel
Content-Type: application/json
{}GET /squareup/v2/refundsGET /squareup/v2/refunds/{refund_id}POST /squareup/v2/refunds
Content-Type: application/json
{
"idempotency_key": "unique-refund-key",
"payment_id": "{payment_id}",
"amount_money": {
"amount": 500,
"currency": "USD"
},
"reason": "Customer requested refund"
}GET /squareup/v2/customersGET /squareup/v2/customers/{customer_id}POST /squareup/v2/customers
Content-Type: application/json
{
"given_name": "John",
"family_name": "Doe",
"email_address": "john.doe@example.com",
"phone_number": "+15551234567"
}PUT /squareup/v2/customers/{customer_id}
Content-Type: application/json
{
"email_address": "john.updated@example.com"
}DELETE /squareup/v2/customers/{customer_id}POST /squareup/v2/customers/search
Content-Type: application/json
{
"query": {
"filter": {
"email_address": {
"exact": "john.doe@example.com"
}
}
}
}POST /squareup/v2/orders
Content-Type: application/json
{
"order": {
"location_id": "{location_id}",
"line_items": [
{
"name": "Item 1",
"quantity": "1",
"base_price_money": {
"amount": 1000,
"currency": "USD"
}
}
]
},
"idempotency_key": "unique-order-key"
}GET /squareup/v2/orders/{order_id}PUT /squareup/v2/orders/{order_id}
Content-Type: application/json
{
"order": {
"location_id": "{location_id}",
"version": 1
},
"fields_to_clear": ["line_items"]
}POST /squareup/v2/orders/search
Content-Type: application/json
{
"location_ids": ["{location_id}"],
"query": {
"filter": {
"state_filter": {
"states": ["OPEN"]
}
}
}
}POST /squareup/v2/orders/batch-retrieve
Content-Type: application/json
{
"location_id": "{location_id}",
"order_ids": ["{order_id_1}", "{order_id_2}"]
}GET /squareup/v2/catalog/listWith type filter:
GET /squareup/v2/catalog/list?types=ITEM,CATEGORYGET /squareup/v2/catalog/object/{object_id}POST /squareup/v2/catalog/object
Content-Type: application/json
{
"idempotency_key": "unique-catalog-key",
"object": {
"type": "ITEM",
"id": "#new-item",
"item_data": {
"name": "Coffee",
"description": "Hot brewed coffee",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "#small-coffee",
"item_variation_data": {
"name": "Small",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 300,
"currency": "USD"
}
}
}
]
}
}
}DELETE /squareup/v2/catalog/object/{object_id}POST /squareup/v2/catalog/batch-upsert
Content-Type: application/json
{
"idempotency_key": "unique-batch-key",
"batches": [
{
"objects": [...]
}
]
}POST /squareup/v2/catalog/search
Content-Type: application/json
{
"object_types": ["ITEM"],
"query": {
"text_query": {
"keywords": ["coffee"]
}
}
}GET /squareup/v2/catalog/infoGET /squareup/v2/inventory/{catalog_object_id}POST /squareup/v2/inventory/counts/batch-retrieve
Content-Type: application/json
{
"catalog_object_ids": ["{object_id_1}", "{object_id_2}"],
"location_ids": ["{location_id}"]
}POST /squareup/v2/inventory/changes/batch-create
Content-Type: application/json
{
"idempotency_key": "unique-inventory-key",
"changes": [
{
"type": "ADJUSTMENT",
"adjustment": {
"catalog_object_id": "{object_id}",
"location_id": "{location_id}",
"quantity": "10",
"from_state": "NONE",
"to_state": "IN_STOCK"
}
}
]
}GET /squareup/v2/inventory/adjustments/{adjustment_id}GET /squareup/v2/invoices?location_id={location_id}GET /squareup/v2/invoices/{invoice_id}POST /squareup/v2/invoices
Content-Type: application/json
{
"invoice": {
"location_id": "{location_id}",
"order_id": "{order_id}",
"primary_recipient": {
"customer_id": "{customer_id}"
},
"payment_requests": [
{
"request_type": "BALANCE",
"due_date": "2026-02-15"
}
],
"delivery_method": "EMAIL"
},
"idempotency_key": "unique-invoice-key"
}PUT /squareup/v2/invoices/{invoice_id}
Content-Type: application/json
{
"invoice": {
"version": 1,
"payment_requests": [
{
"uid": "{payment_request_uid}",
"due_date": "2026-02-20"
}
]
},
"idempotency_key": "unique-update-key"
}POST /squareup/v2/invoices/{invoice_id}/publish
Content-Type: application/json
{
"version": 1,
"idempotency_key": "unique-publish-key"
}POST /squareup/v2/invoices/{invoice_id}/cancel
Content-Type: application/json
{
"version": 1
}DELETE /squareup/v2/invoices/{invoice_id}?version=1POST /squareup/v2/invoices/search
Content-Type: application/json
{
"query": {
"filter": {
"location_ids": ["{location_id}"],
"customer_ids": ["{customer_id}"]
}
}
}Square uses cursor-based pagination. List endpoints return a cursor field when more results exist:
GET /squareup/v2/payments?cursor={cursor_value}Response includes pagination info:
{
"payments": [...],
"cursor": "next_page_cursor_value"
}Continue fetching by passing the cursor value in subsequent requests until no cursor is returned.
const response = await fetch(
'https://gateway.maton.ai/squareup/v2/locations',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);
const data = await response.json();import os
import requests
response = requests.get(
'https://gateway.maton.ai/squareup/v2/locations',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()2026-02-07T01:59:28.459Z)idempotency_key to prevent duplicate operationscurl -g when URLs contain brackets to disable glob parsingjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments| Status | Meaning |
|--------|---------|
| 400 | Missing Square connection or bad request |
| 401 | Invalid or missing Maton API key |
| 403 | Insufficient OAuth scopes |
| 404 | Resource not found |
| 429 | Rate limited |
| 4xx/5xx | Passthrough error from Square API |
{
"errors": [
{
"category": "INVALID_REQUEST_ERROR",
"code": "NOT_FOUND",
"detail": "Could not find payment with id: {payment_id}"
}
]
}MATON_API_KEY environment variable is set:echo $MATON_API_KEYpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFsquareup. For example:https://gateway.maton.ai/squareup/v2/locationshttps://gateway.maton.ai/v2/locationsIf you receive a 403 error with INSUFFICIENT_SCOPES, the OAuth connection doesn't have the required permissions. Create a new connection and ensure you grant all necessary permissions during OAuth authorization.
AI Usage Analysis
Analysis is being generated… refresh in a few seconds.
Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
Connect to 100+ APIs (Google Workspace, Microsoft 365, GitHub, Notion, Slack, Airtable, HubSpot, etc.) with managed OAuth. Use this skill when users want to...
Build, debug, and deploy websites using HTML, CSS, JavaScript, and modern frameworks following production best practices.
YouTube Data API integration with managed OAuth. Search videos, manage playlists, access channel data, and interact with comments. Use this skill when users want to interact with YouTube. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Scaffold, test, document, and debug REST and GraphQL APIs. Use when the user needs to create API endpoints, write integration tests, generate OpenAPI specs, test with curl, mock APIs, or troubleshoot HTTP issues.
Search for jobs across LinkedIn, Indeed, Glassdoor, ZipRecruiter, Google Jobs, Bayt, Naukri, and BDJobs using the JobSpy MCP server.