Order Flow (Webhook)

1. Customer completes purchase on Square (online or in-person).
2. Square sends order.created or order.updated to POST /webhooks/square.
3. NOMA Sync verifies signature, checks idempotency (square_order_{id}), fetches full order/customer if needed.
4. Syncs only when state is COMPLETED or OPEN with payment; finds/creates constituent (or uses default), creates gift with mapped fund, writes sync_log.
5. Order appears in LGL and in Dashboard → Syncs.

Order Flow (Polling Backup)

Every 15 minutes (when Square is configured), the Worker fetches recent orders from the Square API. Any order not already in sync_log is synced. Recovered orders appear in Syncs with sync_method "polling".

Manual Resync (Dashboard)

If an order didn't sync (e.g. webhook was down) or you need to re-push:

1. Open Dashboard → Square Orders.
2. Find the order by ID or customer.
3. Click Resync. Optionally use Force to bypass idempotency (creates a new sync attempt; may create a second gift in LGL if not careful).

API: POST /api/square/orders/:orderId/resync (admin/super_admin). Query ?force=true skips idempotency in production; in development idempotency is skipped by default.

Refunds and Cancellations

As of the current implementation, refunds and canceled orders are not automatically synced (e.g. no PATCH to LGL gift to mark refunded). A separate plan exists for Square refunds/cancelled orders. Check Syncs for failed rows and LGL for manual adjustment if needed.

Multiple Line Items

One Square order → one LGL gift. The gift amount is the order total; line items may be summarized in the gift description or notes.