Square

SKILL.md

---
name: squareup
description: |
  Square API integration with managed OAuth. Install only if you need Square administration. Connect with the least-privileged Square account and OAuth scopes available, verify the intended connection ID before each request, and revoke unused connections promptly. This integration can mutate Square data — approve only specific write actions after checking the exact endpoint, account, resource ID, and consequence.
  For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
  Requires network access and valid Maton API key.
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: 🧠
    requires:
      env:
        - MATON_API_KEY
---

# Square

Access the Square API with managed OAuth authentication. See the API Reference below for supported endpoints.

## Quick Start

```bash
# List locations
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
```

## Base URL

```
https://api.maton.ai/squareup/{endpoint-path}
```

The gateway proxies requests to `connect.squareup.com` and automatically injects your OAuth token. Only the endpoints documented in the API Reference section below are supported — always use specific endpoint paths from that section rather than constructing arbitrary paths.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**IMPORTANT:** Treat `MATON_API_KEY` as a secret — do not log it, include it in chats or prompts visible to others, or expose it in shared files or outputs. The key authenticates with Maton, and the Square connection is independently scoped via OAuth. Use least-privileged Square OAuth scopes, revoke unused connections promptly, and if the key is compromised, rotate it immediately at [maton.ai/settings](https://maton.ai/settings).

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Square OAuth connections at `https://api.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'squareup'}).encode()
req = urllib.request.Request('https://api.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
```

### Get Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:**
```json
{
  "connection": {
    "connection_id": "{connection_id}",
    "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.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
```

### Specifying Connection

If you have multiple Square connections, specify which one to use with the `Maton-Connection` header:

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/squareup/v2/locations')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

If you have multiple connections, always include this header to ensure requests go to the intended account.

## Security & Permissions

- Access is scoped to the Square resources permitted by the connected account's OAuth scopes. Only install if you need Square administration. Use the least-privileged OAuth scopes available and revoke unused connections promptly.
- **Default to read-only operations.** Always start by listing or retrieving resources to confirm account, location, and resource identifiers before proposing any changes.
- **All write operations require explicit user approval with specific identifiers.** Before executing any POST, PUT, or DELETE call:
  1. Retrieve and display the target resource (customer name, order ID, catalog item, location) so the user can verify.
  2. Clearly describe the intended effect (e.g., "This will process a $50.00 payment at location 'Main Store' (ID: L123) for customer 'John Doe'").
  3. Wait for explicit user confirmation before proceeding.
- **Financial operations require extra caution.** Any action that affects money, billing, or access must include a summary of consequences (amounts, affected accounts, locations) and require confirmation.

## API Reference

### Locations

#### List Locations

```bash
GET /squareup/v2/locations
```

#### Get Location

```bash
GET /squareup/v2/locations/{location_id}
```

#### Create Location

```bash
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"
    }
  }
}
```

#### Update Location

```bash
PUT /squareup/v2/locations/{location_id}
Content-Type: application/json

{
  "location": {
    "name": "Updated Location Name"
  }
}
```

### Merchants

#### Get Merchant

```bash
GET /squareup/v2/merchants/me
```

#### List Merchants

```bash
GET /squareup/v2/merchants
```

### Payments

#### List Payments

```bash
GET /squareup/v2/payments
```

With filters:

```bash
GET /squareup/v2/payments?location_id={location_id}&begin_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00Z
```

#### Get Payment

```bash
GET /squareup/v2/payments/{payment_id}
```

#### Create Payment

```bash
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}"
}
```

#### Update Payment

```bash
PUT /squareup/v2/payments/{payment_id}
Content-Type: application/json

{
  "payment": {
    "tip_money": {
      "amount": 200,
      "currency": "USD"
    }
  },
  "idempotency_key": "unique-key-67890"
}
```

#### Complete Payment

```bash
POST /squareup/v2/payments/{payment_id}/complete
Content-Type: application/json

{}
```

#### Cancel Payment

```bash
POST /squareup/v2/payments/{payment_id}/cancel
Content-Type: application/json

{}
```

### Refunds

#### List Refunds

```bash
GET /squareup/v2/refunds
```

#### Get Refund

```bash
GET /squareup/v2/refunds/{refund_id}
```

#### Create Refund

```bash
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"
}
```

### Customers

#### List Customers

```bash
GET /squareup/v2/customers
```

#### Get Customer

```bash
GET /squareup/v2/customers/{customer_id}
```

#### Create Customer

```bash
POST /squareup/v2/customers
Content-Type: application/json

{
  "given_name": "John",
  "family_name": "Doe",
  "email_address": "john.doe@example.com",
  "phone_number": "+15551234567"
}
```

#### Update Customer

```bash
PUT /squareup/v2/customers/{customer_id}
Content-Type: application/json

{
  "email_address": "john.updated@example.com"
}
```

#### Delete Customer

```bash
DELETE /squareup/v2/customers/{customer_id}
```

#### Search Customers

```bash
POST /squareup/v2/customers/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "email_address": {
        "exact": "john.doe@example.com"
      }
    }
  }
}
```

### Orders

#### Create Order

```bash
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 Order

```bash
GET /squareup/v2/orders/{order_id}
```

#### Update Order

```bash
PUT /squareup/v2/orders/{order_id}
Content-Type: application/json

{
  "order": {
    "location_id": "{location_id}",
    "version": 1
  },
  "fields_to_clear": ["line_items"]
}
```

#### Search Orders

```bash
POST /squareup/v2/orders/search
Content-Type: application/json

{
  "location_ids": ["{location_id}"],
  "query": {
    "filter": {
      "state_filter": {
        "states": ["OPEN"]
      }
    }
  }
}
```

#### Batch Retrieve Orders

```bash
POST /squareup/v2/orders/batch-retrieve
Content-Type: application/json

{
  "location_id": "{location_id}",
  "order_ids": ["{order_id_1}", "{order_id_2}"]
}
```

#### Pay Order

```bash
POST /squareup/v2/orders/{order_id}/pay
Content-Type: application/json

{
  "idempotency_key": "unique-key",
  "payment_ids": ["{payment_id}"]
}
```

### Catalog

#### List Catalog

```bash
GET /squareup/v2/catalog/list
```

With type filter:

```bash
GET /squareup/v2/catalog/list?types=ITEM,CATEGORY
```

#### Get Catalog Object

```bash
GET /squareup/v2/catalog/object/{object_id}
```

#### Upsert Catalog Object

```bash
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 Catalog Object

```bash
DELETE /squareup/v2/catalog/object/{object_id}
```

#### Batch Upsert Catalog Objects

```bash
POST /squareup/v2/catalog/batch-upsert
Content-Type: application/json

{
  "idempotency_key": "unique-batch-key",
  "batches": [
    {
      "objects": [...]
    }
  ]
}
```

#### Search Catalog Objects

```bash
POST /squareup/v2/catalog/search
Content-Type: application/json

{
  "object_types": ["ITEM"],
  "query": {
    "text_query": {
      "keywords": ["coffee"]
    }
  }
}
```

#### Get Catalog Info

```bash
GET /squareup/v2/catalog/info
```

### Inventory

#### Retrieve Inventory Count

```bash
GET /squareup/v2/inventory/{catalog_object_id}
```

#### Batch Retrieve Inventory Counts

```bash
POST /squareup/v2/inventory/counts/batch-retrieve
Content-Type: application/json

{
  "catalog_object_ids": ["{object_id_1}", "{object_id_2}"],
  "location_ids": ["{location_id}"]
}
```

#### Batch Change Inventory

```bash
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"
      }
    }
  ]
}
```

#### Retrieve Inventory Adjustment

```bash
GET /squareup/v2/inventory/adjustments/{adjustment_id}
```

### Invoices

#### List Invoices

```bash
GET /squareup/v2/invoices?location_id={location_id}
```

#### Get Invoice

```bash
GET /squareup/v2/invoices/{invoice_id}
```

#### Create Invoice

```bash
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"
}
```

#### Update Invoice

```bash
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"
}
```

#### Publish Invoice

```bash
POST /squareup/v2/invoices/{invoice_id}/publish
Content-Type: application/json

{
  "version": 1,
  "idempotency_key": "unique-publish-key"
}
```

#### Cancel Invoice

```bash
POST /squareup/v2/invoices/{invoice_id}/cancel
Content-Type: application/json

{
  "version": 1
}
```

#### Delete Invoice

```bash
DELETE /squareup/v2/invoices/{invoice_id}?version=1
```

#### Search Invoices

```bash
POST /squareup/v2/invoices/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "location_ids": ["{location_id}"],
      "customer_ids": ["{customer_id}"]
    }
  }
}
```

### Team Members

#### Search Team Members

```bash
POST /squareup/v2/team-members/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "location_ids": ["{location_id}"],
      "status": "ACTIVE"
    }
  }
}
```

#### Get Team Member

```bash
GET /squareup/v2/team-members/{team_member_id}
```

#### Update Team Member

```bash
PUT /squareup/v2/team-members/{team_member_id}
Content-Type: application/json

{
  "team_member": {
    "given_name": "Updated Name"
  }
}
```

### Loyalty

#### List Loyalty Programs

```bash
GET /squareup/v2/loyalty/programs
```

#### Get Loyalty Program

```bash
GET /squareup/v2/loyalty/programs/{program_id}
```

#### Search Loyalty Accounts

```bash
POST /squareup/v2/loyalty/accounts/search
Content-Type: application/json

{
  "query": {
    "customer_ids": ["{customer_id}"]
  }
}
```

#### Create Loyalty Account

```bash
POST /squareup/v2/loyalty/accounts
Content-Type: application/json

{
  "loyalty_account": {
    "program_id": "{program_id}",
    "mapping": {
      "phone_number": "+15551234567"
    }
  },
  "idempotency_key": "unique-key"
}
```

#### Accumulate Loyalty Points

```bash
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"
}
```

### Payment Links (Online Checkout)

#### List Payment Links

```bash
GET /squareup/v2/online-checkout/payment-links
```

#### Get Payment Link

```bash
GET /squareup/v2/online-checkout/payment-links/{id}
```

#### Create Payment Link

```bash
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}"
  }
}
```

#### Update Payment Link

```bash
PUT /squareup/v2/online-checkout/payment-links/{id}
Content-Type: application/json

{
  "payment_link": {
    "version": 1,
    "description": "Updated description"
  }
}
```

#### Delete Payment Link

```bash
DELETE /squareup/v2/online-checkout/payment-links/{id}
```

### Cards

#### List Cards

```bash
GET /squareup/v2/cards
GET /squareup/v2/cards?customer_id={customer_id}
```

#### Get Card

```bash
GET /squareup/v2/cards/{card_id}
```

#### Create Card

```bash
POST /squareup/v2/cards
Content-Type: application/json

{
  "idempotency_key": "unique-key",
  "source_id": "cnon:card-nonce-ok",
  "card": {
    "customer_id": "{customer_id}"
  }
}
```

#### Disable Card

```bash
POST /squareup/v2/cards/{card_id}/disable
```

### Payouts

#### List Payouts

```bash
GET /squareup/v2/payouts
GET /squareup/v2/payouts?location_id={location_id}
```

#### Get Payout

```bash
GET /squareup/v2/payouts/{payout_id}
```

#### List Payout Entries

```bash
GET /squareup/v2/payouts/{payout_id}/payout-entries
```

### Bank Accounts

#### List Bank Accounts

```bash
GET /squareup/v2/bank-accounts
```

#### Get Bank Account

```bash
GET /squareup/v2/bank-accounts/{bank_account_id}
```

### Terminal

#### List Terminal Checkouts

```bash
GET /squareup/v2/terminals/checkouts
```

#### Create Terminal Checkout

```bash
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 Terminal Checkout

```bash
GET /squareup/v2/terminals/checkouts/{checkout_id}
```

#### Search Terminal Checkouts

```bash
POST /squareup/v2/terminals/checkouts/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "status": "COMPLETED"
    }
  }
}
```

#### Cancel Terminal Checkout

```bash
POST /squareup/v2/terminals/checkouts/{checkout_id}/cancel
```

## Pagination

Square uses cursor-based pagination. List endpoints return a `cursor` field when more results exist:

```bash
GET /squareup/v2/payments?cursor={cursor_value}
```

Response includes pagination info:

```json
{
  "payments": [...],
  "cursor": "next_page_cursor_value"
}
```

Continue fetching by passing the cursor value in subsequent requests until no cursor is returned.

## Code Examples

### JavaScript

```javascript
const response = await fetch(
  'https://api.maton.ai/squareup/v2/locations',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();
```

### Python

```python
import os
import requests

response = requests.get(
    'https://api.maton.ai/squareup/v2/locations',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()
```

## Notes

- All amounts are in the smallest currency unit (e.g., cents for USD: 1000 = $10.00)
- IDs are alphanumeric strings
- Timestamps are in ISO 8601 format (e.g., `2026-02-07T01:59:28.459Z`)
- Most write operations require an `idempotency_key` to prevent duplicate operations
- Some endpoints require specific OAuth scopes (CUSTOMERS_READ, ORDERS_READ, ITEMS_READ, INVOICES_READ, etc.)
- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing
- IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments

## Error Handling

| 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 |

### Error Response Format

```json
{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "NOT_FOUND",
      "detail": "Could not find payment with id: {payment_id}"
    }
  ]
}
```

### Troubleshooting: API Key Issues

1. Check that the `MATON_API_KEY` environment variable is set:

```bash
echo $MATON_API_KEY
```

2. Verify the API key is valid by listing connections:

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
```

### Troubleshooting: Invalid App Name

1. Ensure your URL path starts with `squareup`. For example:

- Correct: `https://api.maton.ai/squareup/v2/locations`
- Incorrect: `https://api.maton.ai/v2/locations`

### Troubleshooting: Insufficient Scopes

If 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.

## Resources

- [Square API Overview](https://developer.squareup.com/docs)
- [Square API Reference](https://developer.squareup.com/reference/square)
- [Payments API](https://developer.squareup.com/reference/square/payments-api)
- [Customers API](https://developer.squareup.com/reference/square/customers-api)
- [Orders API](https://developer.squareup.com/reference/square/orders-api)
- [Catalog API](https://developer.squareup.com/reference/square/catalog-api)
- [Inventory API](https://developer.squareup.com/reference/square/inventory-api)
- [Invoices API](https://developer.squareup.com/reference/square/invoices-api)
- [Locations API](https://developer.squareup.com/reference/square/locations-api)
- [Team Members API](https://developer.squareup.com/reference/square/team-api)
- [Loyalty API](https://developer.squareup.com/reference/square/loyalty-api)
- [Online Checkout API](https://developer.squareup.com/reference/square/online-checkout-api)
- [Cards API](https://developer.squareup.com/reference/square/cards-api)
- [Payouts API](https://developer.squareup.com/reference/square/payouts-api)
- [Bank Accounts API](https://developer.squareup.com/reference/square/bank-accounts-api)
- [Terminal API](https://developer.squareup.com/reference/square/terminal-api)
- [Maton Community](https://discord.com/invite/dBfFAcefs2)
- [Maton Support](mailto:support@maton.ai)