Connect Square
Sync your Square catalog and sales history into MenuWright with OAuth, encrypted token storage, and daily refresh.
Connecting Square is the fastest way to bring a real menu and sales history into MenuWright. The connection is strictly read-only: MenuWright never writes to your Square account.
MenuWright's Square integration currently runs against the sandbox environment while the production app is under review. Real-restaurant onboarding is not available until Square approves the production app.
What you get
| Capability | Detail |
|---|---|
| Catalog sync | Menu items, categories, variations, and prices, mapped into MenuWright's item model |
| Sales sync | Itemized order history, aggregated into daily sales records for the analysis window |
| Initial sync | On first connection: full catalog plus ~90 days of orders, followed by an analysis trigger |
| Ongoing sync | Daily background sync keeps catalog and sales current |
The connection flow
- From onboarding or Settings → Data, choose Connect Square.
- MenuWright redirects you to Square's authorization page.
- You authorize read access to the seller's catalog and order history.
- Square redirects back; MenuWright exchanges the code and stores the tokens.
- The initial sync starts in the background — the onboarding review step polls for the arriving items.
The exchange runs under your signed-in session, so connected tokens always bind to your restaurant — never to whoever initiated the authorization URL. The OAuth state is a signed, short-lived token bound to your tenant, and a mismatched state is rejected.
How tokens are handled
- Tokens are encrypted at rest (Fernet) before they touch the database.
- Square access tokens expire after 24 hours. When a sync detects an expired token, MenuWright automatically refreshes it using the stored refresh token — Square rotates the refresh token on every use, so the new token pair is re-encrypted and persisted.
- If the refresh token itself has expired or been revoked (refresh tokens last 30 days), the connection enters a needs reconnect state. The Data and Settings pages show a "Reconnect Square" prompt instead of a silently dead "Connected" indicator, and syncs pause until you reconnect.
- Disconnecting from Settings → Data revokes the OAuth grant on Square's side and clears the stored credentials. The revoke is idempotent, so disconnecting an already-expired connection is safe.
The sync contract
| Item | Detail |
|---|---|
| Menu items | Fetched from the Square Catalog API, including categories (resolved via the catalog's category objects) |
| Sales | Fetched from the Square Orders API and normalized into daily SalesRecord rows |
| Schedule | Daily sync via Celery beat at 04:00 UTC |
| Sync history | Every import is logged with source, records imported, and status |
Limitations
- Sandbox-only today. Production Square app review is the long pole for real restaurants; the OAuth flow itself is implemented and tested against sandbox.
- Read-only. MenuWright syncs catalog and sales aggregates; it never modifies your Square data.
- One location model. The adapter is built for a single merchant's catalog and orders today.