# Integration flow Source: https://docs.layoutmobile.com/architecture/integration-flow How a customer order moves from app to payment and kitchen, and how Square and Layout stay in sync. This page walks through the main flows: **customer order and payment**, **Square ↔ Layout sync**, **kitchen display**, and **engagement features**. It's conceptual — focused on what happens, not how it's built internally. ## Customer order and payment 1. **Customer** opens the branded app, picks a **location**, and browses the menu. Items that are sold out in Square are automatically reflected in the app. 2. **Cart and order** — The customer builds a cart and proceeds to checkout. If the customer selects a future pickup time, that slot is validated and stored with the order. 3. **Promotions and discounts** — Before payment, applicable discounts are evaluated and applied automatically. This includes welcome offers for first-time customers, any active in-app promotions, and Square-side discounts. The specifics of how eligibility is determined are handled by the backend. 4. **Checkout** — The app sends the order and payment details to the backend. The backend verifies the customer's identity, confirms the order is in a valid state, and creates the payment in Square using a unique key to prevent duplicate charges. 5. **Confirmation** — Square processes the payment; the order is confirmed and made available to the kitchen. The customer sees confirmation in the app. 6. **Post-checkout** — Loyalty balance is updated and the customer may receive a push notification confirming any points earned. Payment always goes through Square. Layout never holds card data or settles funds. ## Gift cards Customers can interact with Square gift cards entirely within the app: * **Purchase** — Buy a new Square gift card from within the app. * **Reload** — Add funds to an existing gift card. * **Link** — Connect an existing physical gift card to the account. * **Redeem** — Apply a gift card balance at checkout. * **Designs** — Each merchant can configure a custom gift card design through the dashboard. Gift card balances and data are always sourced from Square. ## Keeping Square and Layout in sync * **At connect** — After Square OAuth is authorized, Layout syncs your locations and catalog immediately. * **Event-driven** — When things change in Square (catalog, inventory, locations, loyalty), Square sends event notifications to Layout. We verify each one and update the relevant data for your account. * **Daily scheduled sync** — A scheduled job runs every 24 hours as a backstop to catch anything that may have been missed, ensuring data stays accurate overnight. * **Inventory** — Sold-out states update in near real-time when Square reports inventory changes. Square is the source of truth. Layout reflects what's in Square — it never writes catalog or location data back. ## Loyalty * Loyalty balance and program data sync both on a schedule and after relevant checkout actions. * When a customer earns loyalty points, a push notification is automatically sent to let them know. * Enrollment and redemption happen in the app; the backend coordinates with Square's Loyalty system. ## Kitchen display and order status * **Layout KDS** — Staff open the kitchen panel, pick a location, and see that location's orders. Moving an order through status (accepted → making → ready → completed) updates what the customer sees in the app, and can trigger a push notification or iOS Live Activity on their lock screen. * **Square KDS** — If you use Square's kitchen display only, the app shows order confirmation and an estimated pickup time. * **Square Expeditor** — A workflow variant where Square's fulfillment transitions map to Layout's status model, suited for counter-service operations. ## End-to-end picture ``` Customer app Backend Square | | | | Place order | | |------------------>| | | (Discounts, | | | pickup time) | | | | Create payment | | |------------------->| | |<-------------------| | Order confirmed | | |<------------------| | | | Loyalty sync | | |<-------------------| | (Push, status, | | | Live Activity) | | |<------------------| | Catalog / locations: Square --> (events + daily sync) --> Layout --> App & Dashboard Inventory: Square --> (inventory events) --> Layout --> App (sold-out) Gift cards: Square <-> Layout backend <-> Customer app Kitchen: Layout panel <-> order status <-> Customer app (Layout KDS) ``` ## What this means for shop owners * **Your menu is always current** — Changes in Square appear in the app automatically. No manual syncing needed. * **Payments stay in Square** — Every dollar processed goes through your Square account. Layout never touches settlement. * **Orders are reliable** — The system is designed so duplicate taps, network retries, and edge cases don't result in double charges or lost orders. * **Your kitchen workflow stays yours** — Whether you use Layout KDS, Square KDS, or Square Expeditor, orders flow to where your team already works. For more on Square sync and connection, see [Square integration](/integrations/square). For reliability and payment safety, see [Reliability](/reliability). # Architecture overview Source: https://docs.layoutmobile.com/architecture/overview High-level structure of Layout Mobile: customer app, dashboard, kitchen panel, and backend. This page describes how Layout Mobile is structured at a high level — without internal implementation details, data schemas, or proprietary logic. It's for technical evaluators and partners who need a clear mental model of how the system works. ## System components Layout Mobile has four main surfaces and a backend that ties them together: | Component | Role | Users | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | **Customer app** | Branded iOS app for browsing menu, choosing location, ordering, tracking status, and engaging with loyalty, gift cards, and promotions. | End customers | | **Merchant dashboard** | Web app for branding, Square connection, location management, order settings, loyalty, promotions, analytics, and more. | Owners and operators | | **Kitchen panel** | Web-based panel for viewing and updating orders by location. Supports Layout KDS, Square KDS, and Square Expeditor. | Kitchen and store staff | | **Backend** | Hosted APIs, Square sync, event handling, payment orchestration, push notifications, and secure credential management. | Used by all of the above | All data is **company-scoped**: every request and record is tied to a specific merchant account (and often a specific location). There is no shared data across merchants. ## How data flows * **Square** is the source of truth for catalog, locations, and payments. Layout connects via OAuth and maintains a secure, per-merchant connection. * **Catalog and locations** sync from Square into the platform at connect time and stay current via Square event notifications and a daily scheduled job. * **Inventory** reflects Square's sold-out states in near real-time. * **Orders** originate in the app, move through the backend, and payment is processed by Square. Order status is tracked in the platform and surfaced to both the kitchen and the customer app. * **Billing** — Merchant subscriptions are managed via Stripe. Plan status gates access to features like ordering and gift cards. Square owns catalog, locations, and money movement. Stripe owns subscription billing. Layout owns the app experience, order lifecycle, engagement features, and kitchen display. ## Authentication and access * **Customer app** — Customers sign in via phone-based authentication. Every action (ordering, checkout, loyalty) requires a valid session tied to that customer. * **Dashboard and panel** — Owners and staff sign in with role-based access. Permissions are scoped to the company and, where relevant, specific locations. Only authorized users can change settings, connect Square, or view sensitive data. * **Square** — The connection is per merchant. Tokens are stored securely and automatically refreshed. All Square event notifications are verified before processing. No customer or merchant credentials are mixed across merchants. ## Where things run * **Customer app** — Native iOS app; communicates with the backend for ordering, status, and account data. * **Dashboard and panel** — Web apps; use the same backend and tenant-scoped data. * **Backend** — Hosted and operated entirely by Layout. No merchant-hosted servers or databases are required. Merchants connect Square and configure the dashboard; Layout handles the rest. ## Integration points | External system | Layout's role | | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | **Square** | OAuth connection, catalog/location/inventory/loyalty/gift card sync, payment creation, event-driven updates. | | **Stripe** | Subscription billing; plan status kept in sync via Stripe event notifications. | | **Push / Live Activity** | Customer notifications for order status and loyalty, plus iOS Live Activity for lock-screen order tracking. | | **Apple App Store** | Each merchant's branded app is submitted as a distinct App Store listing with per-brand deep link support. | ## Next steps * [Integration flow](/architecture/integration-flow) — How a customer order moves from app to payment and kitchen. * [Square integration](/integrations/square) — What we sync, how the connection works, and how updates flow. * [Multi-location](/multi-location) — How companies and locations are modeled. # Business value Source: https://docs.layoutmobile.com/business-value What Layout Mobile delivers for local and multi-location coffee shops and how it fits with Square and your operations. This page summarizes the **business value** of Layout Mobile for coffee shop owners, technical evaluators, and partners or investors. It stays high-level and avoids implementation detail. ## For multi-location coffee shop owners ### Your brand, your app You get a **native iOS app** under your brand — your business name, logo, colors, and menu — published to the App Store as its own listing. Customers download your app, choose a location, order ahead, and pay with card or Apple Pay. You don't build or host the app; Layout runs the platform and keeps it in sync with your Square account. ### Works with what you already use Layout is built for merchants who already use **Square** for POS and payments. We don't replace Square; we add a mobile ordering, engagement, and kitchen layer on top: * **Catalog and locations** — Managed in Square; synced to the app automatically via webhooks and a daily job. * **Payments** — Processed by Square. Settlement and reporting stay in your Square account. Zero transaction fees from Layout. * **Loyalty** — If you use Square Loyalty, customers can see their balance, enroll, and earn points in the app. * **Kitchen** — Use our kitchen panel (Layout KDS), Square KDS, or Square Expeditor; we support all three. ### Customer engagement built in Every plan includes tools to bring customers back: * **Push notifications** — Unlimited. Send targeted messages or let loyalty point notifications fire automatically. * **Announcement cards** — Surface in-app messages about promotions, new menu items, or store news. * **Welcome offer** — Automatically apply a first-order discount for new customers. * **Promotions & featured items** — Run in-app promotions (with optional Square discount codes) and highlight specific menu items. ### Gift cards (Plus) On the Plus plan, customers can purchase, reload, link, and redeem **Square gift cards** directly in the app. Designs are configurable per brand. ### One dashboard, all locations * **Dashboard** — Configure branding, which locations are active, order and pickup behavior, promotions, and analytics in one place. * **Kitchen panel** — See orders by location and move them through status. Optional customer-facing status and push notifications with Layout KDS. * **Analytics** — Revenue and order analytics by location, with engagement metrics on Plus. ## Plans at a glance | | **Starter** | **Pro** | **Plus** | | --------------------------------- | ----------- | ----------- | ----------- | | **Price** | \$0/month | \$250/month | \$500/month | | Branded iOS app | ✓ | ✓ | ✓ | | Customer accounts & order history | ✓ | ✓ | ✓ | | Square Loyalty integration | ✓ | ✓ | ✓ | | Unlimited push notifications | ✓ | ✓ | ✓ | | Announcement cards | ✓ | ✓ | ✓ | | Basic dashboard | ✓ | ✓ | ✓ | | **Mobile ordering** | — | ✓ | ✓ | | Real-time menu sync with Square | — | ✓ | ✓ | | Zero transaction fees | — | ✓ | ✓ | | Revenue analytics | — | ✓ | ✓ | | Featured items | — | ✓ | ✓ | | Advanced dashboard | — | ✓ | ✓ | | **Square gift cards** | — | — | ✓ | | Priority support | — | — | ✓ | | White-glove onboarding | — | — | ✓ | | Quarterly performance reviews | — | — | ✓ | | Detailed engagement metrics | — | — | ✓ | | **Additional location** | N/A | +\$150/mo | +\$150/mo | See [Pricing](/pricing) for the full breakdown. ## For technical evaluators ### Clear integration model * **Square as source of truth** — Catalog, locations, inventory, and payments flow through Square. We sync and orchestrate; we don't duplicate payment processing or replace your POS. * **Square OAuth with auto-refresh** — Connect once; tokens are refreshed automatically. No manual reconnect needed. * **14 Square scopes** — Catalog, locations, payments, customers, loyalty, gift cards, and inventory — covering the full feature set. * **Webhook-driven** — 11 Square webhook event types handled: catalog, inventory, location, loyalty, customer, order, fulfillment, and payment events. * **Secure, tenant-scoped** — OAuth tokens and data scoped by company and location. `merchantToCompany` routing ensures webhooks never cross tenant boundaries. * **Reliability** — Idempotent payment creation to avoid double charges; order state checks; daily scheduled sync backstop; auto-refreshing Square tokens. ### Architecture and operations * **Hosted platform** — No merchant-hosted servers or databases. Layout runs the backend, dashboard, and panel. * **Stripe billing** — Subscription management via Stripe; billing status (active, past\_due, canceled) gates features at the plan level. * **Per-brand App Store listing** — Each merchant's app is submitted to the App Store under their brand with per-company Universal Links via dynamically served Apple App Site Association files. ## For investors and partners ### Market and product fit Layout targets **local and multi-location coffee shops (and similar quick-service merchants) on Square** who want: * A **branded mobile app** without building and maintaining their own. * **Alignment with Square** — same catalog, locations, payments, loyalty, and gift cards they already use. * **Engagement tools** — push notifications, promotions, welcome offers, and announcements out of the box. * **Multi-location and kitchen** — one app, location-aware orders, and flexible KDS support. The product is scoped to **add value on top of Square**, not replace it — reducing integration risk and fitting how these merchants already operate. ### Technical credibility * **Integration depth** — Square OAuth, 14 API scopes, 11 webhook event types, idempotent payments, catalog/inventory/loyalty/gift card sync. * **Security and reliability** — Tenant isolation, no card data in Layout, HMAC-verified webhooks, idempotency, auto-token refresh, daily sync backstop. * **Multi-tenant, multi-location** — Company and location model is explicit; data and access are scoped accordingly; additional locations billed transparently. * **Engagement layer** — Push notifications, loyalty integration, promotions, and gift cards create retention loops beyond simple ordering. ## Summary | Audience | Takeaway | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Owners** | Branded iOS app for all locations; works with Square POS, loyalty, and gift cards; one dashboard and optional kitchen panel; engagement tools on every plan. | | **Evaluators** | Square-first, deeply integrated (14 scopes, 11 webhook types); tenant and location isolation; idempotent payments; auto-refreshing tokens; verified webhooks; Stripe billing. | | **Investors / partners** | Clear product-market fit (Square-based local/multi-location); three-tier pricing (Starter/Pro/Plus) with location add-ons; documented architecture and security. | For the rest of the story, start with [Overview](/overview) and [Pricing](/pricing), then [Architecture overview](/architecture/overview), [Square integration](/integrations/square), [Reliability](/reliability), and [Security](/security). # GIT SYNC AND PR Source: https://docs.layoutmobile.com/docs/GIT_SYNC_AND_PR # Sync with remote and open a PR Use this when someone else has pushed to the repo and you want your MacBook up to date, then contribute via a PR instead of pushing directly to main. ## Prompt for Cursor Copy and paste this when you need to sync and prepare a PR: ``` Sync this repo with the remote: fetch origin, pull main so my working copy is up to date with the latest from GitHub. Then create a new branch for my changes (e.g. fix/docs-config or feature/whatever) so I can make edits and open a PR instead of pushing to main. Run the git commands and tell me the branch name to use for the PR. ``` Cursor will run the right `git fetch`, `git pull`, and `git checkout -b ` (or equivalent) and remind you to push the branch and open a PR. ## Commands to run yourself From the repo root (`LayoutDocs`): ```bash theme={null} # 1. Get latest from GitHub git fetch origin git pull origin main # 2. Create a branch for your work (pick a short name) git checkout -b fix/docs-config # 3. Make your edits, then commit and push the branch git add . git commit -m "Your message" git push -u origin fix/docs-config ``` Then on GitHub: open the repo → you’ll usually see “Compare & pull request” for the branch you just pushed → open the PR. ## If pull has conflicts If `git pull origin main` reports conflicts: ```bash theme={null} git status # see conflicted files # Edit the files to resolve conflicts, then: git add . git commit -m "Merge main and resolve conflicts" ``` Then continue with your branch and push. # Quickstart Source: https://docs.layoutmobile.com/getting-started/quickstart How merchants get started with Layout Mobile: choose a plan, connect Square, configure the app, and go live. This page outlines the path from signup to a live branded app. It's aimed at **merchant owners** and **evaluators** who want to understand the flow without touching the dashboard. ## Prerequisites * A **Square account** with your locations and catalog set up. * Your **business branding** (logo, primary color, business name) ready. No need to change your existing POS or KDS setup; Layout connects to what you already have. ## Step 1: Create your account and choose a plan Merchants sign up through the Layout dashboard. Account creation is standard: email, company/business details, and verification. Once in, you choose a plan: | Plan | Price | What it unlocks | | ----------------------- | ------------ | ------------------------------------------------------------------------------------------ | | **Starter** | \$0/month | Branded app, Square loyalty, push notifications, announcements. No ordering. | | **Pro** | \$250/month | Everything in Starter plus mobile ordering, real-time catalog sync, and revenue analytics. | | **Plus** | \$500/month | Everything in Pro plus Square gift cards, priority support, and white-glove onboarding. | | **Additional location** | +\$150/month | Each active location beyond the one included in Pro or Plus. | Billing is handled via Stripe. A trial promotional offer may be available at signup. ## Step 2: Connect Square Layout uses **Square OAuth** so you authorize access once from your Square account: 1. In the dashboard, start the **Connect Square** flow. 2. You're redirected to Square to sign in (if needed) and approve the requested permissions (catalog, locations, payments, loyalty, gift cards, inventory, and more). 3. After you allow access, Layout receives and stores a secure connection to your Square account. Tokens are stored in a secure, tenant-scoped way and **automatically refreshed** by the backend — you never have to reconnect due to token expiry. 4. Layout then performs an initial sync of **locations** and **catalog** (items and categories) into the platform. From then on, catalog and location changes in Square are reflected in the app via Square webhooks and a daily scheduled sync job. You keep managing menu and locations in Square; the app stays in sync. ## Step 3: Configure branding and app behavior In the dashboard you set: * **Branding** — Business name, logo (light/dark), primary CTA color. These drive the look of the customer app. * **Locations** — Which Square locations are enabled for mobile ordering (all or a subset). Additional active locations beyond your plan's included count are billed at \$150/month each. * **Order and pickup** — Settings like default pickup time estimates, scheduled ordering slots, and prep lead times for the kitchen. * **Catalog source** — Whether to sync from standard Square categories or Square Menus (if your account uses the Square Menus feature). The customer-facing iOS app reads this configuration so it shows your name, colors, menu, and locations. ## Step 4: App submission Layout prepares and submits your branded iOS app to the App Store on your behalf. The app is published under your brand name with your own App Store listing. This is a one-time process handled as part of onboarding — you don't manage Xcode or provisioning profiles. Universal Links (so shared links open the app directly) are also configured per brand. ## Step 5: Configure engagement features (optional) From the dashboard you can also set up: * **Push notifications** — Available on all plans; send targeted messages to your customer base. Loyalty point notifications fire automatically via Square webhooks. * **Announcement cards** — In-app cards to highlight promotions or news. * **Welcome offer** — A first-order discount for new customers, automatically deduped by phone, device, and email. * **Promotions** — In-app promotions with optional Square discount code integration. * **Featured items** — Highlight specific menu items at the top of the app. * **Gift cards** — Available on Plus; configure gift card designs and let customers buy, reload, and redeem Square gift cards in the app. ## Step 6: Kitchen display (optional) If you use **Layout's kitchen panel**: * Staff sign in and select a **location**. * Orders for that location appear on the panel with status (accepted → making → ready → completed). * Updating status drives what the customer sees in the app (and optional push notifications or iOS Live Activity). If you use **Square KDS** or **Square Expeditor**, you leave kitchen display in Square; the app can still show an estimated pickup time and order confirmation. ## Step 7: Go live Once Square is connected, branding and locations are set, and (if applicable) the kitchen panel is configured: * **Customers** download your branded app from the App Store, choose a location, browse the menu, and pay with Square (card or Apple Pay). * **Orders** appear in your kitchen (Layout panel, Square KDS, or Square Expeditor, depending on config). * **You** keep using Square for payments, reporting, and menu/location management; the app and panel stay aligned with Square. ## Summary | Step | What happens | | ----------------- | ------------------------------------------------------------------------------------------------ | | 1. Account & plan | Sign up, choose Starter / Pro / Plus, billing via Stripe. | | 2. Square | OAuth connect → secure token storage with auto-refresh → initial sync of locations and catalog. | | 3. Config | Set branding, active locations, order/pickup behavior, and catalog source. | | 4. App submission | Layout submits your branded iOS app to the App Store (one-time, handled by Layout). | | 5. Engagement | Optionally configure push, announcements, welcome offer, promotions, featured items, gift cards. | | 6. Kitchen | Optionally use Layout KDS, Square KDS, or Square Expeditor. | | 7. Live | Customers order in the app; payments in Square; orders in your kitchen. | No code or infrastructure is required on the merchant side. The technical work is connecting Square once and configuring the dashboard; Layout handles the rest. For more detail on how data flows end-to-end, see [Integration flow](/architecture/integration-flow). For how we keep payments and sync reliable and secure, see [Reliability](/reliability) and [Security](/security). # Introduction Source: https://docs.layoutmobile.com/index Layout Mobile gives local and multi-location coffee shops a branded mobile app built on Square — with mobile ordering, loyalty, gift cards, push notifications, and kitchen display. A branded app for your locations, menu, and loyalty — without rebuilding your stack. Architecture, integrations, and operations built for reliability and security. ## What is Layout Mobile? Layout Mobile is a **white-label mobile ordering platform** for local and multi-location merchants who already run on **Square**. You keep your existing point-of-sale and kitchen display; we add a customer-facing iOS app that stays in sync with your catalog, locations, loyalty, and payments. * **Branded experience** — Your name, logo, and colors in a native iOS app published to the App Store under your brand. * **Square-native** — Connect once via Square OAuth; catalog, locations, payments, and loyalty flow through your existing Square account. * **Multi-location** — One app, all locations. Customers choose a store; orders and status remain location-aware. * **Kitchen-ready** — Works with Layout KDS, Square KDS, or Square Expeditor. Orders appear where your team already works. * **Loyalty, gift cards & promotions** — Surface Square Loyalty balance and enrollment, sell and reload Square gift cards, and run in-app promotions and welcome offers directly from the app. * **Push notifications & announcements** — Send unlimited push notifications and in-app announcement cards to keep customers engaged. This documentation is for **owners**, **technical evaluators**, and **partners** who want a clear picture of how the system works, how it integrates with Square, and how we think about reliability and security. ## Who this is for | Audience | What you'll find here | | ------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **Multi-location coffee shop owners** | How Layout fits with Square, what each plan includes, and how locations and branding work. | | **Technical evaluators** | High-level architecture, integration flow, reliability and security principles, and multi-tenant design. | | **Investors & partners** | Platform scope, integration strategy, pricing model, and how we position reliability and security. | ## What you get * **Customer app** — Branded iOS app: menu, locations, cart, checkout (Square), loyalty, gift cards, promotions, order status, and push notifications. * **Merchant dashboard** — Branding, Square connection, locations (synced from Square), order settings, loyalty config, promotions, analytics, and featured items. * **Kitchen panel** — Location-based order display and status flow (accepted → making → ready → completed), with support for Layout KDS, Square KDS, and Square Expeditor. Payments and catalog stay in Square; Layout orchestrates the app experience, order flow, engagement features, and kitchen display so everything stays consistent across locations. ## Next steps Product scope, key concepts, and how the pieces fit together. Starter, Pro, and Plus plans with per-feature breakdown. How merchants get started: connect Square, configure the app, and go live. What we sync, how OAuth works, and how webhooks stay in sync. # Square integration Source: https://docs.layoutmobile.com/integrations/square How Layout connects to Square, what we sync, and how catalog, locations, payments, and inventory stay in sync. Layout Mobile is built for merchants who already use **Square** for POS, payments, and often loyalty. This page explains how we integrate with Square — what we sync, how the connection works, and what that means for your data. ## 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. You keep one place to manage menu and money; we keep the app and kitchen in sync. ## Connecting your Square account Layout uses **Square OAuth 2.0** — a standard authorization flow used across the Square ecosystem: 1. From the Layout dashboard, start **Connect Square**. 2. You're redirected to Square to sign in and grant access. 3. After you authorize, Layout securely stores the connection — scoped to your company only. 4. The backend automatically keeps the connection active over time; you never need to manually reconnect. 5. Layout runs an **initial sync** of your locations and catalog right after connecting. The connection uses only the permissions needed to run the features on your plan. We don't document the specific technical permissions here. ## 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. | We do **not** write catalog or locations back to Square from the app or dashboard. All menu and location edits happen in Square; Layout reflects them. ## 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. For a broader view of security, see [Security](/security). For reliability and sync details, see [Reliability](/reliability). # Multi-location Source: https://docs.layoutmobile.com/multi-location How Layout Mobile models companies and locations so one app serves all your stores. Layout Mobile is built for **multi-location** merchants. One brand, one app, many stores. This page explains how we model that — for owners who run several locations and for technical evaluators who care about data and access boundaries. ## Company and locations * **Company** — One merchant account (e.g. your coffee shop brand). All configuration, Square connection, branding, and users are scoped to this company. In our model, "tenant" means one company. * **Locations** — A company has many locations. In Layout, locations are **synced from Square**. Each Square location can be enabled or disabled for mobile ordering in the dashboard. The customer app shows only enabled locations for that company. So: **one company, many locations**. The app doesn't require a separate build per location; a single branded app (configured for that company) shows all of that company's enabled locations. The customer chooses a location, then orders; the order is tied to that location. ## How it works in the app 1. **Location picker** — The customer sees the list of your enabled locations (name, address, hours) and selects one before ordering. The app may remember the last location used. 2. **Menu and catalog** — Catalog is synced from Square at the company level. Items and categories can be shared across locations or vary by location, depending on how you manage them in Square. The app reflects what's available for the selected location. 3. **Orders** — Every order is stored with a company ID and a location ID. Kitchen display and reporting are location-aware: staff pick a location in the panel and see that location's orders; analytics can be broken down by location. So: **one app, one company, many locations** — with location chosen per order and enforced in the backend. ## Dashboard and panel * **Dashboard** — Branding and Square connection are company-wide. You can enable or disable specific locations for mobile ordering and set order/pickup behavior (e.g. default pickup time, catalog source). The location list comes from Square and stays in sync via webhooks and daily scheduled sync. * **Kitchen panel** — Staff sign in and **select a location**. The panel then shows orders for that location only. Status updates (accepted → making → ready → completed) apply to that location's orders. Switching location switches the view. So: **company-level config**, **location-level operations** in the panel and in order data. ## Pricing for additional locations Every Pro and Plus plan includes **one location** for mobile ordering. Each additional active location beyond that is billed at **\$150/month**: | Plan | Included locations | Additional location | | ------------------- | ------------------ | ------------------- | | **Starter** | N/A (no ordering) | N/A | | **Pro** (\$250/mo) | 1 | +\$150/mo each | | **Plus** (\$500/mo) | 1 | +\$150/mo each | The add-on quantity is calculated automatically from the number of locations with active mobile ordering enabled in the dashboard. Enabling or disabling a location adjusts your subscription at the next billing cycle. For a full plan comparison, see [Pricing](/pricing). ## Data and access * **Data scope** — All data (orders, catalog, locations, Square connection) is keyed by company. Orders and panel state are also keyed by location. There is no cross-company access; within a company, location is used to filter and scope. * **Square** — Your Square account may have many locations; we sync them all and let you choose which are active in the app. Catalog can be shared across locations in Square; we reflect that. ## Why it matters * **For owners** — One app for your brand; customers pick the store; you manage which locations are live and see orders and analytics by location. * **For evaluators** — Clear tenant (company) and location model; no cross-tenant data; location is required for ordering and kitchen display; additional locations are billed transparently. For how data flows from Square into the app and panel, see [Integration flow](/architecture/integration-flow) and [Square integration](/integrations/square). # Overview Source: https://docs.layoutmobile.com/overview Product scope, key concepts, and how Layout Mobile fits with Square and your operations. Layout Mobile is built for **local and multi-location coffee shops (and similar merchants) that use Square**. The goal is simple: add a branded mobile ordering experience, customer engagement features, and kitchen visibility — without replacing your POS or KDS. ## Key concepts ### White-label mobile app Customers see **your** brand: your business name, logo, colors, and menu. The app is a native iOS experience published to the App Store under your brand name. You don't host or build the app yourself; Layout runs the platform and keeps it in sync with your Square account and your dashboard settings. ### Square as the source of truth * **Catalog** — Items and categories sync from Square. Edits in Square flow into the app via webhooks and scheduled sync. Layout supports both standard Square categories and Square Menus. * **Locations** — Your Square locations are synced; you choose which are available for mobile ordering. * **Payments** — Checkout uses Square (card, Apple Pay). Funds and reporting stay in your Square account. * **Loyalty** — When you use Square Loyalty, customers can see their balance, enroll, and earn points in the app. Loyalty data stays in sync via webhooks and scheduled jobs. * **Gift cards** — Customers can purchase, reload, and redeem Square gift cards directly in the app. Gift card designs are configurable per brand. * **Inventory** — Sold-out states sync from Square so unavailable items are reflected in the app automatically. You keep one place to manage menu, payments, and loyalty; the app reflects that. ### Multi-location by design Everything is **company-first, then location**. One merchant account (company) has many locations. The app shows your locations; the customer picks one, then orders. Orders and kitchen display are scoped to that location. The dashboard and panel let you manage and view by location. ### Customer engagement * **Push notifications** — Send unlimited push notifications to customers on all plans. Notifications can also fire automatically when loyalty points are earned. * **Announcement cards** — Surface in-app announcements to highlight promotions, new menu items, or store news. * **Welcome offer** — A first-order discount for new customers, automatically deduped across phone number, device, and email. * **Promotions** — Merchant-created in-app promotions, with optional Square discount code integration. * **Featured items** — Highlight specific menu items at the top of the app. ### Kitchen display (KDS) Layout supports three modes: * **Layout KDS** — Our kitchen panel shows orders and status (accepted → making → ready → completed). Status updates drive customer-facing order status and optional push notifications or iOS Live Activity. * **Square KDS** — You keep using Square's kitchen display; the app shows an estimated pickup time instead of live status. * **Square Expeditor** — A variant where Square's fulfillment flow (PROPOSED → PREPARED) maps to Layout's status model. The "prepared" state triggers the ready signal without a separate making step. Your existing kitchen workflow stays central; we adapt to it. ### Scheduled ordering Customers can place orders for a specific future pickup time. The backend computes time slots based on your configured timezone and operating hours. Kitchen prep lead times (`kdsPrepLeadMinutes`) are factored in so orders are surfaced to staff at the right moment. ## What's in scope | Layer | What Layout provides | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Customer app** | Branded iOS app: menu, locations, cart, Square checkout, loyalty, gift cards, promotions, order status, push notifications, iOS Live Activity. | | **Merchant dashboard** | Branding, Square connection, location settings, order/pickup behavior, loyalty config, promotions, announcements, featured items, analytics, and operations. | | **Kitchen panel** | Location picker, order list, status flow, scheduled prep support; works alongside or instead of Square KDS. | | **Backend** | Secure APIs and sync: Square OAuth with auto-refresh, catalog/location/loyalty/inventory webhooks, order creation and payment, idempotent payment handling, gift cards, push notifications. | ## What stays in your control * **Square** — All payment processing, settlement, and Square reporting. * **Catalog and locations** — Managed in Square; we sync and respect your choices (e.g. which locations are enabled). * **Branding and behavior** — Logo, CTA color, app name, and ordering rules (e.g. pickup time estimates) are set in the dashboard. ## Plans Layout Mobile is available in three tiers. See [Pricing](/pricing) for a full breakdown. | Plan | Price | Best for | | ----------------------- | ------------ | --------------------------------------------------------------------------------- | | **Starter** | \$0/month | Branded app with loyalty and engagement features — no mobile ordering. | | **Pro** | \$250/month | Full mobile ordering, real-time sync, and revenue analytics. | | **Plus** | \$500/month | Multi-location scaling, gift cards, priority support, and white-glove onboarding. | | **Additional location** | +\$150/month | Each location beyond the one included in Pro or Plus. | ## Next steps * [Pricing](/pricing) — Full plan and feature comparison. * [Architecture overview](/architecture/overview) — How the system is structured at a high level. * [Integration flow](/architecture/integration-flow) — How data moves from Square and through the app and kitchen. * [Square integration](/integrations/square) — What we sync and how we connect. # Pricing Source: https://docs.layoutmobile.com/pricing Layout Mobile plans — Starter, Pro, and Plus — with a full feature breakdown and location add-on pricing. Layout Mobile is available in three plans, billed monthly via Stripe. All plans include a branded iOS app published to the App Store under your brand. ## Plans **\$0 / month** Marketing and engagement layer for local brands. Branded app with loyalty and customer engagement — no mobile ordering. **\$250 / month** Full mobile ordering and revenue growth. The most popular plan for active merchants. **\$500 / month** Multi-location scaling, gift cards, priority support, and white-glove onboarding. **Additional location add-on:** \$150/month per active location beyond the one included in Pro or Plus. *** ## Feature comparison | Feature | Starter | Pro | Plus | | ------------------------------------- | :-----: | :------------: | :------------: | | **App & Brand** | | | | | Branded iOS App Store listing | ✓ | ✓ | ✓ | | Custom logo, colors, and name | ✓ | ✓ | ✓ | | Customer accounts & order history | ✓ | ✓ | ✓ | | Universal Links (deep linking) | ✓ | ✓ | ✓ | | **Engagement** | | | | | Unlimited push notifications | ✓ | ✓ | ✓ | | Announcement cards | ✓ | ✓ | ✓ | | Welcome offer (first-order discount) | ✓ | ✓ | ✓ | | In-app promotions | ✓ | ✓ | ✓ | | **Square Integration** | | | | | Square OAuth connection | ✓ | ✓ | ✓ | | Square Loyalty integration | ✓ | ✓ | ✓ | | Loyalty push notifications | ✓ | ✓ | ✓ | | Basic dashboard access | ✓ | ✓ | ✓ | | **Mobile Ordering** | | | | | Mobile ordering for pickup | — | ✓ | ✓ | | Real-time menu sync with Square | — | ✓ | ✓ | | Inventory / sold-out sync | — | ✓ | ✓ | | Scheduled pickup time ordering | — | ✓ | ✓ | | Zero transaction fees | — | ✓ | ✓ | | Square discount code integration | — | ✓ | ✓ | | Featured items | — | ✓ | ✓ | | Revenue & order analytics | — | ✓ | ✓ | | Advanced dashboard | — | ✓ | ✓ | | Kitchen panel (Layout KDS) | — | ✓ | ✓ | | Square KDS / Square Expeditor support | — | ✓ | ✓ | | iOS Live Activity (order tracking) | — | ✓ | ✓ | | **Multi-location** | | | | | Locations included | N/A | 1 | 1 | | Additional locations | N/A | +\$150/mo each | +\$150/mo each | | **Gift Cards** | | | | | Square gift card purchase & reload | — | — | ✓ | | Gift card link by GAN | — | — | ✓ | | Custom gift card designs | — | — | ✓ | | **Support** | | | | | Standard support | ✓ | ✓ | ✓ | | Priority support | — | — | ✓ | | White-glove onboarding | — | — | ✓ | | Quarterly performance reviews | — | — | ✓ | | Detailed engagement metrics | — | — | ✓ | *** ## Additional location pricing Pro and Plus plans each include **one active location** for mobile ordering. Each additional location enabled in the dashboard is billed at **\$150/month**. The add-on quantity is calculated automatically — enabling or disabling a location in the dashboard adjusts your subscription at the next billing cycle. **Example:** A Plus merchant with 4 active locations pays $500 + (3 × $150) = **\$950/month**. *** ## Frequently asked questions **What counts as a location?** A location is any Square location you have enabled for mobile ordering in the Layout dashboard. Locations you've synced from Square but left disabled don't count toward your add-on total. **Can I switch plans?** Yes. Plan changes (e.g. Starter → Pro, Pro → Plus) are handled via Stripe and prorated automatically. **Is there a trial?** A promotional trial offer may be available at signup. Check the dashboard at sign-up for current offers. **How is billing handled?** Billing is monthly via Stripe. Your card is charged at the start of each billing period. Stripe webhooks keep your plan status in sync with the platform in real time. **What happens if payment fails?** If a payment fails, your subscription status moves to `past_due`. Layout's backend tracks this status and may restrict ordering features until the subscription is resolved. You'll receive billing notifications from Stripe. *** Ready to get started? See the [Quickstart](/getting-started/quickstart) or [contact us](https://layoutmedia.org) for a demo. # Reliability Source: https://docs.layoutmobile.com/reliability How Layout Mobile handles failures, retries, and consistency so orders, payments, and sync stay correct. This page describes how we approach **reliability** — for shop owners who want to know their orders are safe, and for technical evaluators who care about correctness under retries, duplicates, and partial failures. ## Payment safety **The problem** — Networks fail and customers sometimes tap "Pay" twice. Without care, that could create duplicate charges. **How we handle it** — Every payment request is designed so that retries and duplicates don't result in a second charge. The backend also checks order state before creating any payment — if an order is already paid, no new charge is attempted. These two layers of protection work together so a customer is never billed twice for a single order. Payment always flows through Square. Layout never holds card data or settles funds. ## Square connection reliability Square OAuth tokens are automatically refreshed by the backend before they expire. Your Square connection stays active indefinitely — you never need to manually reconnect or worry about token expiry interrupting your store. ## Keeping data in sync * **Event-driven** — When things change in Square (catalog, inventory, locations, loyalty), Square sends event notifications and Layout updates your data promptly. * **Daily scheduled sync** — A scheduled job runs every 24 hours as a backstop. Even if an event was delayed or missed, data converges overnight without any action needed from you. * **Inventory** — Sold-out states update in near real-time so the app reflects what's actually available to customers. * **All sync is per-merchant** — One merchant's data never affects another's. ## Loyalty and notifications Loyalty balance updates sync both on a schedule and immediately after checkout. When a customer earns points, a push notification is queued and delivered asynchronously — so notification delivery never holds up the checkout flow. ## Webhook integrity All incoming Square event notifications are cryptographically verified before Layout acts on them. Events that don't pass verification are rejected. This ensures only legitimate Square signals change your data. ## What we don't guarantee here We don't publish SLAs, uptime numbers, or incident response times in this doc. For formal service commitments, refer to your merchant agreement or [Layout's status page](https://status.layoutmobile.com). ## Summary | Area | How we handle it | | ----------------------- | ------------------------------------------------------------------------------------ | | **Payments** | Duplicate-charge protection at two layers; order state checked before every payment. | | **Square connection** | Tokens auto-refreshed; no manual reconnect needed. | | **Catalog & locations** | Event-driven updates plus daily scheduled sync as a backstop. | | **Inventory** | Near-real-time sold-out sync from Square. | | **Loyalty & push** | Sync on schedule and post-checkout; push delivery queued independently of checkout. | | **Event integrity** | Cryptographic verification on all incoming Square notifications. | For how we protect data and access, see [Security](/security). For how orders and payments flow end-to-end, see [Integration flow](/architecture/integration-flow). # Security Source: https://docs.layoutmobile.com/security How Layout Mobile handles identity, tenant isolation, and protection of sensitive data. This page outlines **security principles** for Layout Mobile — for technical evaluators and partners. We don't document specific ciphers, key lengths, or internal implementations; we focus on how we think about identity, isolation, and sensitive data. ## Tenant isolation Layout is **multi-tenant**: many companies (merchants) on one platform. Isolation is enforced at every layer: * **Data** — All stored data is scoped by company (and often location). There is no shared cross-tenant data; one merchant cannot see or change another's catalog, orders, or configuration. * **APIs** — Requests are authenticated and then scoped to a company. Backend logic and data access enforce that scope; no cross-tenant reads or writes are possible. * **Square** — OAuth tokens and Square API usage are per company. Tokens are stored in a tenant-scoped way and used only for that company's Square calls. * **Webhooks** — Incoming Square webhooks are cryptographically verified and internally routed so that an event from one merchant can never affect another merchant's data. Tenant identity is part of every operation. We don't document internal routing mechanisms or storage structures here. ## Authentication and access control * **Customer app** — Users sign in via phone-based authentication. The backend verifies the session before performing any action (ordering, checkout, accessing loyalty or gift card data). Only the authenticated user can place orders or access their account. * **Dashboard and panel** — Access is controlled by identity and role. Staff and owners are associated with a company. Role-based permissions are enforced so that only authorized users can change branding, Square connection, or view orders and analytics. * **Square connection** — Only authorized dashboard users can connect or disconnect Square. Stored tokens are not exposed in the UI or to the customer app. ## Payment and card data * **No card storage** — Layout does not store raw card numbers or payment data. The customer app uses Square's in-app payment flow to generate a one-time token (nonce), which is sent to the Layout backend and forwarded to Square to create the payment. Card data never touches Layout's systems. * **Square** — All payment processing and settlement happen in Square. PCI scope for card data is Square's. Payments are delegated to Square; Layout only passes payment references and order context. ## Secrets and sensitive credentials * Secrets (OAuth credentials, webhook signing keys, and similar) are not hardcoded or committed to source. They're managed via a secure configuration mechanism and injected at runtime. * Per-tenant Square OAuth tokens are stored securely and used only by backend services for that tenant. They are automatically refreshed before expiry — merchants never need to manually reconnect. * Sensitive push notification credentials are stored in a restricted area of the data store, accessible only to privileged backend services. ## Webhooks and data integrity * All incoming webhooks from Square are cryptographically verified before any data is read or written. Unverified requests are rejected immediately. * Each webhook is processed only for the merchant it belongs to. Cross-tenant processing is not possible by design. ## App identity and Universal Links Each merchant's branded iOS app uses **per-company Universal Links**, so shared links (menu items, short links) open the correct branded app for each merchant. The credentials that power this are stored securely per brand and never exposed publicly. ## Summary | Area | Principle | | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | | **Tenancy** | All data and API access scoped by company and location; no cross-tenant access possible. | | **Identity** | Phone auth for customers; role-based access for dashboard and panel; all actions tied to the authenticated user and company. | | **Payments** | No card data in Layout; nonces only; Square handles all processing and settlement. | | **Secrets** | Not in code or repo; securely managed per-tenant; auto-rotated where applicable. | | **Webhooks** | Cryptographic verification required; tenant-scoped processing; invalid or cross-tenant requests rejected. | For how we avoid duplicate charges and handle retries, see [Reliability](/reliability). For how Square connects and what we sync, see [Square integration](/integrations/square).