Appearance
What is the Square integration?
The Square integration syncs Square online store orders to Little Green Light. When someone buys merchandise (or donates via Square), the order and customer are synced as an LGL constituent and gift.
Integration: Square
Webhook: POST /webhooks/square
Code: apps/worker/src/handlers/square-webhook.ts, lib/square-to-lgl.ts, adapters/square-client.ts
What Gets Synced
| Square Data | LGL | Notes |
|---|---|---|
| Order (total, date, line items) | Gift | Amount, date, source "Square Online Store" |
| Customer (name, email, phone) | Constituent | Find or create by email |
| No customer (e.g. guest) | Default constituent | Configured in Settings |
| Location | Campaign/fund | Via location overrides in Mappings |
| Tender type | Payment type | Auto-detected (CARD, CASH, etc.) |
How It Works
Default Constituent
Orders with no customer (e.g. in-person, guest checkout) are assigned to a default constituent (e.g. "Noma Shop"). Configure email, first name, last name in Dashboard → Settings. The Worker finds or creates that constituent in LGL and attaches such orders to it.
Campaign / Fund Mapping
- Square type default: In Mappings, set the default LGL fund for all Square orders.
- Location overrides: Map specific Square locations to specific LGL funds (Dashboard → Mappings or Square location overrides). Used when you have multiple Square locations and want different funds per location.
Backup Polling
When SQUARE_ACCESS_TOKEN is set, the same 15-minute cron that runs Givebutter polling also fetches recent Square orders (e.g. last 30 minutes). Any order not already in sync_log is synced. Recovered orders appear with sync_method "polling".
Dashboard
- Syncs – Filter by source Square; view payload, error, resync.
- Square Orders – List orders from Square API, enrich customer, Resync to LGL.
- Mappings – Square type default and location overrides.
- Settings – Square default constituent.
Error Handling
- LGL 422 "External Gift ID already exists" – Treated as idempotent (skipped), no retry.
- Invalid signature – 401; check
SQUARE_WEBHOOK_SIGNATURE_KEY. - Missing customer – Default constituent used if configured.