Square API integration with managed OAuth. Process payments, manage customers, orders, catalog, inventory, invoices, loyalty programs, team members, and more...
Real data. Real impact.
Emerging
Developers
Per week
Open source
Skills give you superpowers. Install in 30 seconds.
Access 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)) EOF
https://gateway.maton.ai/squareup/{native-api-path}
Replace
{native-api-path}connect.squareup.comAll requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEY
Environment Variable: Set your API key as
MATON_API_KEYexport MATON_API_KEY="YOUR_API_KEY"
Manage your Square OAuth connections at
https://ctrl.maton.aipython <<'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)) EOF
python <<'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)) EOF
python <<'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)) EOF
Response:
{ "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
urlpython <<'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)) EOF
If you have multiple Square connections, specify which one to use with the
Maton-Connectionpython <<'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)) EOF
If omitted, the gateway uses the default (oldest) active connection.
GET /squareup/v2/locations
GET /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/me
GET /squareup/v2/merchants
GET /squareup/v2/payments
With filters:
GET /squareup/v2/payments?location_id={location_id}&begin_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00Z
GET /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/refunds
GET /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/customers
GET /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}"] }
POST /squareup/v2/orders/{order_id}/pay Content-Type: application/json{ "idempotency_key": "unique-key", "payment_ids": ["{payment_id}"] }
GET /squareup/v2/catalog/list
With type filter:
GET /squareup/v2/catalog/list?types=ITEM,CATEGORY
GET /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/info
GET /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=1
POST /squareup/v2/invoices/search Content-Type: application/json{ "query": { "filter": { "location_ids": ["{location_id}"], "customer_ids": ["{customer_id}"] } } }
POST /squareup/v2/team-members/search Content-Type: application/json{ "query": { "filter": { "location_ids": ["{location_id}"], "status": "ACTIVE" } } }
GET /squareup/v2/team-members/{team_member_id}
PUT /squareup/v2/team-members/{team_member_id} Content-Type: application/json{ "team_member": { "given_name": "Updated Name" } }
GET /squareup/v2/loyalty/programs
GET /squareup/v2/loyalty/programs/{program_id}
POST /squareup/v2/loyalty/accounts/search Content-Type: application/json{ "query": { "customer_ids": ["{customer_id}"] } }
POST /squareup/v2/loyalty/accounts Content-Type: application/json{ "loyalty_account": { "program_id": "{program_id}", "mapping": { "phone_number": "+15551234567" } }, "idempotency_key": "unique-key" }
POST /squareup/v2/loyalty/accounts/{account_id}/accumulate Content-Type: application/json{ "accumulate_points": { "order_id": "{order_id}" }, "location_id": "{location_id}", "idempotency_key": "unique-key" }
GET /squareup/v2/online-checkout/payment-links
GET /squareup/v2/online-checkout/payment-links/{id}
POST /squareup/v2/online-checkout/payment-links Content-Type: application/json{ "idempotency_key": "unique-key", "quick_pay": { "name": "Payment for Service", "price_money": { "amount": 1000, "currency": "USD" }, "location_id": "{location_id}" } }
PUT /squareup/v2/online-checkout/payment-links/{id} Content-Type: application/json{ "payment_link": { "version": 1, "description": "Updated description" } }
DELETE /squareup/v2/online-checkout/payment-links/{id}
GET /squareup/v2/cards GET /squareup/v2/cards?customer_id={customer_id}
GET /squareup/v2/cards/{card_id}
POST /squareup/v2/cards Content-Type: application/json{ "idempotency_key": "unique-key", "source_id": "cnon:card-nonce-ok", "card": { "customer_id": "{customer_id}" } }
POST /squareup/v2/cards/{card_id}/disable
GET /squareup/v2/payouts GET /squareup/v2/payouts?location_id={location_id}
GET /squareup/v2/payouts/{payout_id}
GET /squareup/v2/payouts/{payout_id}/payout-entries
GET /squareup/v2/bank-accounts
GET /squareup/v2/bank-accounts/{bank_account_id}
GET /squareup/v2/terminals/checkouts
POST /squareup/v2/terminals/checkouts Content-Type: application/json{ "idempotency_key": "unique-key", "checkout": { "amount_money": { "amount": 1000, "currency": "USD" }, "device_options": { "device_id": "{device_id}" } } }
GET /squareup/v2/terminals/checkouts/{checkout_id}
POST /squareup/v2/terminals/checkouts/search Content-Type: application/json{ "query": { "filter": { "status": "COMPLETED" } } }
POST /squareup/v2/terminals/checkouts/{checkout_id}/cancel
Square uses cursor-based pagination. List endpoints return a
cursorGET /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 requestsresponse = 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.459Zidempotency_keycurl -gjq$MATON_API_KEY| 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_KEYecho $MATON_API_KEY
python <<'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)) EOF
squareuphttps://gateway.maton.ai/squareup/v2/locationshttps://gateway.maton.ai/v2/locationsIf you receive a 403 error with
INSUFFICIENT_SCOPESNo automatic installation available. Please visit the source repository for installation instructions.
View Installation Instructions
1,500+ AI skills, agents & workflows. Install in 30 seconds. Part of the Torly.ai family.
© 2026 Torly.ai. All rights reserved.