Why Square-first
Many local and multi-location coffee shops run on Square for register, payments, and reporting. Layout adds a branded mobile app and kitchen visibility without replacing that stack. We:- Use Square as the source of truth for catalog, locations, and payments.
- Process payments through Square so funds and reporting stay in your Square account.
- Sync catalog, locations, inventory, and loyalty so the app stays aligned with what you manage in Square.
- Support Square Loyalty, Square gift cards, and Square discount codes natively in the app.
Connecting your Square account
Layout uses Square OAuth 2.0 — a standard authorization flow used across the Square ecosystem:- From the Layout dashboard, start Connect Square.
- You’re redirected to Square to sign in and grant access.
- After you authorize, Layout securely stores the connection — scoped to your company only.
- The backend automatically keeps the connection active over time; you never need to manually reconnect.
- Layout runs an initial sync of your locations and catalog right after connecting.
What we sync
| Data | Direction | How it stays current |
|---|---|---|
| Locations | Square → Layout | Synced at connect; kept current via Square event notifications and a daily scheduled job. |
| Catalog (items, categories) | Square → Layout | Synced at connect; updated when Square sends catalog change events. Supports both standard Square categories and Square Menus. |
| Inventory | Square → Layout | Sold-out states update automatically when Square reports inventory changes, so the app reflects availability in near real-time. |
| Loyalty (if enabled) | Square ↔ Layout | Loyalty program and account data sync on a schedule and after relevant checkout actions. |
| Gift cards (if used) | Square ↔ Layout | Purchase, reload, linking, and redemption coordinated through Square; gift card data always sourced from Square. |
Payments
- Checkout — The customer pays using Square’s payment flow (card or Apple Pay) in the app. A one-time payment token is sent to the Layout backend, which creates the payment in Square on the customer’s behalf.
- Idempotency — Each payment is sent with a unique key so that network retries or accidental double-taps can’t create a second charge.
- Settlement and reporting — All settlement and reporting stay in Square. Layout charges zero transaction fees and does not hold card data.
Square event handling
Layout listens for Square event notifications to keep data current. When Square tells us something has changed — catalog, inventory, loyalty, locations, orders — we update the relevant data for that merchant. All events are cryptographically verified before processing, and each event is handled only for the merchant it belongs to. We don’t publish the specific event types or internal handling logic here.KDS modes
| Mode | How it works |
|---|---|
| Layout KDS | Orders and status managed in the Layout kitchen panel. Customer-facing status, push notifications, and iOS Live Activity are driven by kitchen staff actions. |
| Square KDS | You keep using Square’s kitchen display. The app shows order confirmation and an estimated pickup time instead of live status. |
| Square Expeditor | A workflow variant where Square’s fulfillment state transitions map directly to Layout’s ready signal. Useful for counter-service operations. |
Security and isolation
- OAuth tokens are stored per company and used only for that company’s Square API calls — never shared across tenants.
- All incoming Square events are cryptographically verified and tenant-scoped before any processing occurs.
- Customer identity is verified before any payment is created; order state is checked to prevent duplicate or invalid charges.