square-commerce-opslisted
Install: claude install-skill Verstige/square-commerce-ops
# Square Catalog Management
## When this applies
- User needs to create new products in their Square-powered online store
- User needs to update inventory counts for existing products
- User needs to cross-reference manufacturer model numbers with Square SKUs
- User needs to pull **sales totals** — by date range, by location, or by team member
- Stack: Square API (v2) — Catalog, Inventory, Payments, Orders, Reports, Team — proxied through Next.js API routes in the app, deployed on Railway
## Architecture pattern
Square catalog management follows a three-tier architecture:
```
Square API (cloud)
↑↓ HTTPS
the app API route (middleware — holds SQUARE_ACCESS_TOKEN)
↑↓ HTTPS
catalog admin page (browser — calls the app via proxy)
```
The browser NEVER calls Square directly — all requests go through the the app API route which holds the Square access token in its Railway environment variables.
## Creating new catalog items
### Via the app API (recommended)
If an endpoint exists at the app, POST to it:
```bash
curl -X POST 'https://api.example.com/api/catalog/inventory' \
-H 'Content-Type: application/json' \
-d '{
"products": [
{
"title": "Product Name",
"sku": "SKU123",
"price": 99.99,
"description": "Description text"
}
]
}'
```
If no the app endpoint exists, create one by adding a POST handler to the
existing `app/api/catalog/inventory/route.ts` in the the app project:
```typescript
export async functio