# Authentication Source: https://help.atlas.kitchen/connect/admin-api/authentication Every request requires two headers. Generate an API token from your [Atlas merchant portal](https://portal.atlas.kitchen/atlas-connect/api-tokens) and pass it as the `X-Api-Key` value: | Header | Value | | - | - | | `X-Api-Key` | Your Atlas API token | | `X-Merchant-Id` | Tells Atlas which merchant the request is for | ## Example ```bash theme={null} curl https://api.atlas.kitchen/admin/v1/menus \ -H "X-Api-Key: your-api-token" \ -H "X-Merchant-Id: your-merchant-id" ``` ## Token security * The portal shows the token plaintext only once at creation — copy it somewhere safe before closing the dialog * Don't share API tokens in public code, screenshots, or client-side code * Store tokens in environment variables or a secret manager * If a token is compromised, revoke it from the portal and generate a new one ## Error response Invalid or missing API token returns `401 Unauthorized`: ```json theme={null} { "type": "Unauthorized", "message": "You did not provide valid credentials for this request", "error_hash": { "api_key": "Check if the API Key is set correctly in the X-Api-Key header" } } ``` # Brand details Source: https://help.atlas.kitchen/connect/admin-api/brands/brand-details get /brands/{id} # Brand list Source: https://help.atlas.kitchen/connect/admin-api/brands/brand-list get /brands Returns all brands for the merchant, including archived brands. # Create cart Source: https://help.atlas.kitchen/connect/admin-api/carts/create-cart post /carts Creates a dine-in cart for a table with optional upfront payment. Always uses POS platform with DINE_IN fulfilment. # Cash voucher details Source: https://help.atlas.kitchen/connect/admin-api/cash-vouchers/cash-voucher-details get /cash_vouchers/{id} # Cash voucher list Source: https://help.atlas.kitchen/connect/admin-api/cash-vouchers/cash-voucher-list get /cash_vouchers Lists cash vouchers for the merchant. Use `status` to filter active, expired, or redeemed vouchers, and `code` to search by voucher code. Cash voucher values are monetary amounts in minor currency units (cents). For example, `5000` means $50.00. Redemption happens through the existing POS cash voucher flow. This endpoint does not register redemption webhooks. # Create cash voucher Source: https://help.atlas.kitchen/connect/admin-api/cash-vouchers/create-cash-voucher post /cash_vouchers Creates a prepaid cash voucher that staff can redeem through the existing POS cash voucher flow. Cash voucher values are monetary amounts in minor currency units (cents). For example, `5000` means $50.00. Voucher codes are normalized by Atlas before storage. `outlet_ids` controls which outlet pickers show the voucher. It does not block redemption at other outlets when staff enter the voucher code manually. Atlas does not emit a standalone cash voucher redemption webhook from this endpoint. External issuers that need close-the-loop redemption callbacks should use a future dedicated redemption event or an order webhook payload that explicitly includes voucher payment details. # Menu create or update Source: https://help.atlas.kitchen/connect/admin-api/menus/menu-create-or-update post /menus Upserts a menu by `identifier`. Creates a new menu if the identifier doesn't exist, or updates the existing one. The full hierarchy (sections, items, modifiers) is synced — orphaned records are removed. # Menu details Source: https://help.atlas.kitchen/connect/admin-api/menus/menu-details get /menus/{id} Returns full menu hierarchy with sections, items, modifier groups, and modifiers. # Menu list Source: https://help.atlas.kitchen/connect/admin-api/menus/menu-list get /menus # Create order Source: https://help.atlas.kitchen/connect/admin-api/orders/create-order post /outlets/{outlet_id}/channels/{channel_id}/orders Creates a new order for the given outlet and channel. Use [Outlet timeslots](/connect/admin-api/timeslots/get-timeslots) to find pickup and delivery timeslots for this outlet and channel. Supports 3-level item nesting, multiple payments, and admin overrides for payment breakdown fields. # Order details Source: https://help.atlas.kitchen/connect/admin-api/orders/order-details get /orders/{id} Returns an order created through the Admin API. # Order details (with identifier) Source: https://help.atlas.kitchen/connect/admin-api/orders/order-details-identifier get /orders/identifier/{identifier} Returns an order created through the Admin API. # Update order Source: https://help.atlas.kitchen/connect/admin-api/orders/update-order patch /orders/{id} Updates an order created through the Admin API. Orders created through other Atlas workflows cannot be updated with this endpoint. Supports `order_items_update_mode` and `order_payments_update_mode` for merge/replace behaviour. # Outlet details Source: https://help.atlas.kitchen/connect/admin-api/outlets/outlet-details get /outlets/{id} # Outlet list Source: https://help.atlas.kitchen/connect/admin-api/outlets/outlet-list get /outlets Returns all outlets for the merchant, including archived outlets. # Outlet stocks Source: https://help.atlas.kitchen/connect/admin-api/stocks/outlet-stocks specs/admin-v1.yaml GET /outlets/{outlet_id}/serving_dates/{serving_date}/stocks Returns available quantity per item for the outlet on the given date. # Tables Source: https://help.atlas.kitchen/connect/admin-api/tables/tables get /outlets/{outlet_id}/tables Returns active tables for the outlet. # Outlet timeslots Source: https://help.atlas.kitchen/connect/admin-api/timeslots/get-timeslots specs/admin-v1.yaml GET /outlets/{outlet_id}/channels/{channel_id}/timeslots Returns pickup and delivery timeslots for the outlet and channel on the given date. # User sync Source: https://help.atlas.kitchen/connect/admin-api/users/user-sync post /users/sync Upserts a user by email or mobile number. For non-guests, creates an Account and UserAccount relationship. External user links are immutable once created. # Run Atlas from your AI assistant Source: https://help.atlas.kitchen/connect/mcp/overview Connect Atlas to Claude or ChatGPT and manage your restaurant in plain language. **Who is this for?** * Owners and managers who want to check numbers or update menus without opening the Merchant Portal * Any Atlas merchant with AI assistant access turned on ## What this does Atlas plugs into Claude and ChatGPT through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), the standard way assistants talk to outside services. Once connected, you ask your assistant a question and it reads or changes your live Atlas data. No exports, no copy-paste. ## What you can ask for * "How did each outlet do yesterday?" * "86 the laksa at Tanjong Pagar until tomorrow." * "Raise all drink prices by 5% on the delivery menu." * "Which items have no cost set, so I can't see margin?" * "Tag every dish that contains shellfish." Your assistant can also build a live dashboard you keep coming back to. See [Quickstart](/connect/mcp/recipes) for prompts that do this. ## What you need first Ask your Atlas account manager to turn on AI assistant access for your merchant. Setup will fail without it. Claude, ChatGPT, Claude Code and Codex all work. Claude is the best fit if you want live dashboards that write back to Atlas. Follow [Set up Atlas in your assistant](/connect/mcp/setup). It takes about two minutes. ## What your assistant can see Your assistant only sees the one merchant you choose when you sign in. It cannot see other merchants on Atlas. Everything it does runs as you, with your permissions. Disconnect at any time from your assistant's connector settings. Your assistant can change live data — prices, stock, orders. Ask it to show you a plan first, then approve. The [example prompts](/connect/mcp/recipes) are written this way. ## Staying up to date New Atlas tools appear in your assistant automatically as we ship them. There is nothing to install or update on your side. **Connector URL:** `https://mcp.atlas.kitchen` ## What should happen Once connected, ask: **"Using Atlas, how many orders did we do yesterday?"** You get a real number from your outlet within a few seconds. Your assistant shows you when it calls an Atlas tool. ## If it doesn't work 1. Check AI assistant access is on for your merchant. Ask your account manager if you're not sure — this is the most common cause. 2. Check Atlas is switched on for that chat. Your assistant ignores Atlas until you turn it on. 3. Check you picked the right merchant when you signed in. The wrong one gives you the wrong outlet's numbers. 4. Reconnect Atlas from your assistant's connector settings. Sign-ins expire. [Setup](/connect/mcp/setup) covers each of these in detail. If it still doesn't work, contact support at [hello@atlas.kitchen](mailto:hello@atlas.kitchen). ## Next steps Two-minute setup for Claude, ChatGPT, Claude Code and Codex Copy-paste prompts for costs, allergens, cross-sells and modifiers # Quickstart Source: https://help.atlas.kitchen/connect/mcp/recipes Copy-paste prompts that put your AI assistant to work on costs, allergens, cross-sells and modifiers. **Who is this for?** * Owners and managers who have already [connected Atlas to their assistant](/connect/mcp/setup) * Anyone who wants a result without writing the prompt themselves ## What this does Each example prompt below is a full prompt. Copy it, paste it into a new chat, and your assistant does the rest against your live Atlas data. Copy the Claude version or the ChatGPT version to match the assistant you connected. They are not interchangeable — each one is written around what that assistant can do. These example prompts read and change live data. Every prompt asks the assistant to show you a plan first. Read it before you approve. ## Example prompt 1: Manage item costs Add and edit the cost of your products from the chat. Changes save straight to the Atlas Merchant Portal. **What your assistant does:** * Builds a live table of your products with cost, price, margin in dollars and margin % * Flags every item with no cost set, so you can see where margin is hiding * Saves your edits back to Atlas rather than keeping them in the chat * Sets up a daily check that tells you when a product is missing a cost ```text wrap theme={null} I want a persisted artifact or interactive UI in chat to manage product cost live using the Atlas connector. Here's what I need it to do: - Shows my product catalogue, with a way to switch between outlets/menus (I likely have more than one, and the combined catalogue may be large). - Lets me view and edit each product's cost/COGS, with price, margin $, and margin % calculated automatically, and flags anything missing a cost. - Pushes my edits back to Atlas directly rather than just storing them locally in the artifact. - Comes with a daily automated check that alerts me if any product is missing a COGS value. Before building, verify your assumptions against my actual data and tools rather than guessing — check the real shape of tool responses, confirm which items are genuine products versus modifiers/options, and reconcile any counts you pull. Ask me if anything about my setup is ambiguous. ``` ```text wrap theme={null} I have the Atlas plugin connected. Set up a reusable Product Cost / COGS Manager workflow for my Atlas account. What I need: - Start by listing my outlets and menus from Atlas. Ask me which outlet/menu to manage if the correct scope is unclear. - Inspect the actual tool responses before designing the workflow. Do not assume the documented schema exactly matches the backend. - Reconcile catalogue counts across the selected outlet and menu. - Treat products placed directly inside menu sections or subsections as genuine sellable menu products. - Exclude modifier choices, options and components—even if they also appear as item or product records. - Flag outlet-linked products that are not actually present on the selected menu separately. For each genuine menu product, show: - Product name - SKU - Atlas product ID - Menu section - Selling price - Current COGS/cost - Margin amount: price minus COGS - Margin percentage: margin divided by price - Status: current, missing COGS or pending change Editing and syncing: - Let me provide COGS edits individually or as a batch in this conversation. - Interpret monetary values in the product's currency and convert them to minor currency units for Atlas. - Before writing, show a concise change summary with old cost, new cost, new margin amount and new margin percentage. - After I approve, update each product in Atlas using update_product with cost_cents. - Important: if cost_cents is absent from the published update_product schema, do not immediately conclude that writes are unsupported. The Atlas backend may still accept it. Safely verify this using a no-op write of an existing cost value before reporting a limitation. - Never change price, tags, modifier groups or other product fields when only updating COGS. - After every write, read the products again from Atlas and verify the stored values. - Report any partial failures clearly and do not claim a product was updated unless verification succeeds. Interface: - Present the catalogue as a compact, searchable table in ChatGPT. - Allow filtering by menu section, missing COGS and pending changes. - If you create a persisted visual interface, do not imply that its buttons can call Atlas directly unless the interface genuinely has authenticated connector access. - If direct connector access is unavailable inside the interface, keep edits in a pending queue and generate a structured sync request that I can submit through this ChatGPT conversation. Automated check: - Ask me what time and timezone the daily check should run. - Create a daily automation that reads the selected Atlas menu, excludes modifiers/options/components, and checks genuine menu products for missing cost_cents. - Notify me only when at least one genuine menu product is missing COGS. - In an alert, include outlet, menu, total genuine products checked, number missing, product name, SKU, product ID, section and selling price. - If no genuine product is missing COGS, do not notify me. Before building or changing anything, verify the outlet, menu, product-versus-modifier rules, catalogue counts, cost read shape and cost write behaviour against my actual Atlas data and tools. ``` ## Example prompt 2: Manage allergen and dietary tags Tag allergens and dietary flags across your menu without opening each product. Changes save straight to the Atlas Merchant Portal. **What your assistant does:** * Bulk-tags products across 14 allergen and dietary flags, including gluten, dairy and alcohol * Keeps your existing tag names consistent instead of inventing new ones * Leaves unrelated tags on the product untouched * Lets you search for items that do — or do not — carry a flag Once your menu is tagged, servers can use Ask Atlas in the Merchant Portal during service to check whether a dish suits a diner, or list every suitable dish on the menu. ```text wrap theme={null} I want a tool to manage allergen and dietary flags for my menu items in Atlas. Here's what I need it to do: - Show me all the products on any of my menus in one place. If my outlet has more than one menu, let me switch between them without starting over. - Let me mark which allergens (gluten, dairy, shellfish, etc.) and other flags like alcohol apply to each item. - Check for existing allergen tags and ensure that new tag additions are formatted consistently. - Save my changes straight back into Atlas as product tags the moment I make them. - Let me search or filter to quickly find items that do (or don't) have a specific flag. I want this to be something I can reopen anytime and it should always show my current menu data, not a snapshot from when it was built. ``` ```text wrap theme={null} Act as my live Atlas Allergen & Dietary Flag Manager inside ChatGPT. Use the connected Atlas plugin as the source of truth. Do not build or redirect me to a standalone website—the workflow must remain in ChatGPT so reads and writes use my authenticated Atlas connection. Start by: 1. Listing my Atlas menus. 2. Asking which menu I want to manage, unless I already named one. 3. Fetching every product on that menu, handling pagination if necessary. 4. Showing a compact, readable view containing: - Product name - Product ID or SKU - Current allergen and dietary product tags - Items with no managed flags Support natural-language requests such as: - "Refresh" - "Show products with gluten" - "Show products without any allergen flags" - "Add crustacean to Shrimp aglio olio" - "Remove fish from Chicken teriyaki skewers" - "Switch to another menu" When I ask to add or remove a flag: 1. Resolve the exact product. Ask me to choose if the name is ambiguous. 2. Re-fetch that product immediately before writing. 3. Read its complete current product_tags list. 4. Add or remove only the requested tag. 5. Preserve every unrelated product tag. 6. Call the Atlas product-update action with the complete updated product_tags list. 7. Re-fetch the product after writing. 8. Report whether the saved Atlas value was verified. Never overwrite the entire tag list using only the allergen tags shown in the conversation. Tags such as cake, promotional tags, or other operational tags must be preserved. Use Atlas's existing exact tag names whenever they already exist. Display friendly labels, but write the canonical value. Examples: - Gluten → allergen-gluten - Milk/dairy → allergen-milk - Egg → allergen-egg - Fish → allergen-fish - Crustacean → allergen-crustacean - Shellfish → allergen-shellfish, only if this is actually the merchant's established tag - Peanut → allergen-peanut - Tree nuts → allergen-tree-nuts - Soy → allergen-soy - Sesame → allergen-sesame - Alcohol → allergen-alcohol - Vegetarian → dietary-vegetarian - Vegan → dietary-vegan Do not silently treat "crustacean" and "shellfish" as interchangeable. If the requested label does not have an established Atlas tag, ask me which canonical tag to use before writing. Do not infer or add allergens from product names, descriptions, or ingredients unless I explicitly ask you to review and suggest possible missing flags. Suggestions must be presented for approval and must not be written automatically. If an Atlas response is plain text rather than structured JSON, parse it carefully and continue; do not assume the action failed solely because the response format differs from its description. A refresh must always make a new Atlas read. Never present cached or embedded data as current. After each successful edit, respond concisely in this format: Updated and verified in Atlas. [Product name] now has: - [tag] - [tag] If the write or verification fails, clearly distinguish: - Write failed - Write succeeded but verification failed - Product could not be resolved Do not claim an update succeeded unless the post-write Atlas read confirms it. ``` ## Example prompt 3: Manage cross-sell groups Set up [cross-sell](/merchant-portal/cross-sell) rules that suggest the right item at the right moment, to lift average order value. **What your assistant does:** * Shows every cross-sell group: what triggers it, what it promotes, and whether it is live * Flags menu items that trigger no active group, so nothing gets left out * Moves items between groups without you looking up any IDs * Creates new groups from a searchable list of your products ```text wrap theme={null} I want to be able to manage my cross-sell rules across my menus in Atlas and clearly identify products that do not trigger a cross-sell. Here's what I want it to do: - Show me every existing cross-sell group at a glance: what triggers it, what it promotes, and whether it's active, filtered by menu. If my outlet has more than one menu, let me switch between them. - Flag any item on my menu that isn't currently triggering an active cross-sell group, so nothing gets missed. - Let me reassign an item from one group to another (or unassign it) by dragging and dropping it, without me having to look up IDs myself. - Let me create a brand-new group by picking which items should trigger it and which items it should promote. - Let me activate or deactivate a group. If there's no delete tool available for this, deactivating is the right substitute — don't try to force a hard delete. A few things to watch for while building this: - Probe each tool once in chat and look at the actual response shape before wiring it into the artifact — don't assume it matches the schema description word for word. - If a call ever returns plain text instead of clean JSON (e.g. it looks like a raw object dump rather than JSON), write a small parser for that format instead of assuming JSON.parse will work. - Make tool calls one at a time rather than firing several at once, and retry a couple of times on failure. Backends like this can be flaky under concurrent requests and throw unrelated-looking errors when hit with parallel calls — spacing calls out avoids most of that. - Keep it as a persisted, live artifact rather than a static one-time render, since group membership changes over time and I'll want to check back on it. ``` ```text wrap theme={null} I have the Atlas plugin connected. Help me manage cross-sell rules across my Atlas menus. Start by reading my actual Atlas setup. Do not assume outlet, menu, product, or cross-sell IDs. What I need: - Let me choose an outlet and menu. - Show every cross-sell group relevant to that menu. - For each group, show: its internal group name, whether it is active, the products that trigger it, and the products it promotes. - Clearly identify menu products that do not trigger any active cross-sell group. - Let me search and filter products, especially uncovered products. - Let me draft these operations without manually finding IDs: move a triggering product between groups, unassign a triggering product, activate or deactivate a group, create a new group by selecting triggering and promoted products. - Cross-sell group names are internal identifiers. Do not describe or treat them as customer-facing labels. Customers see the promoted products, not the group name. - Do not hard-delete groups. If no supported deletion tool exists, deactivate them. Tool-handling requirements: 1. Probe each required Atlas read tool once and inspect its real response before building the workflow. 2. Atlas may return Ruby-style object dumps such as {:key=>value} instead of valid JSON. If that happens, parse the returned format rather than using JSON.parse directly. 3. Make Atlas calls sequentially, not concurrently. 4. Retry failed read or idempotent update calls up to two times with a short delay. 5. Do not automatically retry a non-idempotent group-creation call if the result is uncertain, because that could create a duplicate. 6. Resolve all product and group IDs internally from their names. 7. When changing a group's triggering or promoted products, remember that the Atlas update tool may treat those arrays as full replacements. Preserve every existing member that should remain. 8. After applying changes, re-read the affected groups from Atlas and report exactly what was verified. Artifact and editing workflow: - If ChatGPT can create an interactive artifact that directly calls the Atlas tools, use it. - If a hosted website cannot call the Atlas connector, do not pretend its controls save to Atlas. - In that case, create a draft-mode cross-sell planner: initialise it using the latest Atlas data retrieved in chat; allow local drag-and-drop reassignment, unassignment, activation changes, and new-group drafting; keep the draft in browser storage so it survives a refresh on that device; maintain a consolidated pending-change list; provide a reliable "Copy changes for ChatGPT" button; also display the generated instruction as selectable text in case clipboard access is blocked; clearly label the site as draft mode and state that Atlas has not changed yet. - The copied instruction must include the outlet, menu, internal group names, product names, and all intended operations—never require the user to copy IDs. When I paste a change list back into the conversation: 1. Parse the complete list. 2. Show me a concise summary of what will change. 3. Ask for confirmation only if the instruction is ambiguous, destructive, or conflicts with current Atlas data. 4. Otherwise, apply the changes sequentially. 5. Re-read Atlas and verify the final trigger membership, promoted products, and active status. 6. Clearly distinguish successful changes, skipped changes, and failures. Begin by listing my available outlets and menus, then open the most likely active menu while still giving me a menu selector. ``` ## Example prompt 4: Plan and build modifiers Design meal deals, add-ons and drink pairings, then build them on your live menu. Your assistant advises first, rather than just doing as it is told. **What your assistant does:** * Reads your menu and suggests upsells that fit it, with pricing that still makes margin * Walks you through the trade-offs — flat or tiered price, optional or required, bundle or full price * Shows the diner-facing flow before anything changes * Builds the modifier groups on your menu only after you approve them ```text wrap theme={null} I want help planning and setting up modifiers across my menu — things like meal deals, add-ons, "make it a meal" upgrades, sides, extras, or drink pairings. I may not know exactly what's best, so I'd like you to advise, not just execute. What I'm looking for from you: - Understand my menu first, then suggest add-on ideas that fit it — where there's a natural upsell, what to pair, and roughly how to price it so it feels like value for diners and stays profitable. - Ask me about my goals (higher average order value, moving slow items, simplifying choices, etc.) and tailor recommendations to them. - Walk me through the trade-offs — flat price vs tiered, required vs optional, discounted bundle vs full price — and recommend a default. How I want to work: 1. Ask me what you need to know before proposing anything. 2. Create an artifact or visualise the UI in chat with your proposed add-ons: the diner flow, the options, and the pricing — so I can see it before anything changes. 3. Let me react and adjust in the artifact or UI in chat, and refine the plan with me. 4. Once I'm happy, apply it to my live menu and tidy up any existing messy or inconsistent setups so everything stays clean. 5. Keep the artifact in sync with what's actually live, and flag anything I should check on the diner-facing menu afterwards. Don't change anything on my menu until I've reviewed and confirmed. ``` ```text wrap theme={null} I have the Atlas plugin connected. Help me plan, review, and implement modifiers across my menu. My goal is to increase basket size and average order value through sensible upsells such as meal upgrades, sides, extras, desserts, drink pairings, and bundles. I may not know what will work best, so advise me rather than asking me to define every pairing. Follow this workflow: 1. Understand my goals Ask which outlet or menu to work on and what I want to optimise for, such as: increasing average order value, increasing the number of items per order, improving cross-sell uptake, moving slower-selling items, promoting particular products, or simplifying ordering. Also ask whether I prefer full-price add-ons, discounted bundles, or for you to recommend the best approach. 2. Inspect Atlas before recommending anything Use the Atlas tools to read: outlets and menus, current products and prices, existing modifier and cross-sell groups, active and inactive rules, relevant order history, products commonly purchased together, and current average order value and items per order, where available. Probe the relevant tools and examine their actual response shapes instead of relying solely on their schema descriptions. Keep outlet-specific products separate from merchant-wide test, legacy, or unrelated configurations. 3. Identify the strongest basket-building opportunities Look for natural ordering moments such as: main → side, main → drink, coffee → dessert, cocktail → sharing snack, single item → meal upgrade, multiple complementary items → bundle, checkout → final add-on. Prioritise pairings that: feel relevant to the diner's current selection, add another item to the basket with little decision friction, have evidence of being purchased together, use existing products where possible, avoid presenting too many choices, and are likely to produce a meaningful increase in basket value. Do not recommend add-ons merely because the products exist. Explain why each one is likely to increase uptake or order value. 4. Recommend a plan For each proposal, show: triggering products, exact diner-facing prompt, promoted products, current item prices, potential basket-value increase, whether the choice is optional or required, minimum and maximum selections, whether pricing is full price, discounted, or tiered, why the pairing should increase basket size, and the Atlas configuration required. Where historical data is available, include: current attachment or co-purchase signals, typical basket-value increase, relevant product popularity, and a reasonable uptake hypothesis. Clearly distinguish measured results from estimates or hypotheses. 5. Explain the commercial trade-offs Walk me through: flat versus tiered pricing, optional versus required selections, full-price convenience versus discounted bundles, one strong recommendation versus several choices, product-page prompts versus checkout prompts, and higher add-on value versus lower-friction entry pricing. Recommend a default based on my stated AOV goal. 6. Create a review artifact before changing Atlas Present the proposal as a simple planning artifact, not a marketing website. Prefer: expandable drill-downs for each trigger, a plain pricing and basket-impact table, a list of proposed Atlas changes, and a clear "Draft — nothing live has changed" status. Show the literal prompts and choices diners would encounter so I can visualise the real ordering experience. Let me request changes in ordinary language and keep refining the artifact. 7. Require approval Do not create, update, activate, deactivate, or reassign anything in Atlas until I explicitly say something equivalent to: "Approve and apply." Reviewing the artifact alone does not count as approval. 8. Apply the approved plan After approval: re-read the affected Atlas records to avoid overwriting newer changes, update suitable existing groups instead of creating duplicates, create new groups only when necessary, activate or deactivate groups as approved, preserve unrelated groups and products, and do not hard-delete anything unless Atlas supports it and I explicitly request deletion. For non-idempotent creation calls, check for an existing matching group before creating anything. Do not blindly retry after an uncertain response. 9. Verify and synchronise After writing: read every affected group back from Atlas; verify its label, active state, triggers, promoted products and descriptions; report exactly what succeeded or failed; update the artifact from "Draft" to "Live"; keep the artifact consistent with the verified Atlas configuration; flag anything I should check on the diner-facing menu; and suggest which AOV and attachment metrics to review after launch. Clearly state which sales channels support the cross-sells. Do not imply that Atlas-owned cross-sells automatically appear on third-party platforms such as GrabFood or Foodpanda. GrabFood also does not support deep nested modifiers. Start by asking only the questions that would materially change your recommendation. Do not make any menu changes yet. ``` ## What should happen Your assistant reads your Atlas data first, then shows you what it found or what it plans to change. Nothing on your menu changes until you approve it. Check the result in the [Atlas Merchant Portal](https://portal.atlas.kitchen). Costs, tags and groups appear there within a few seconds of the assistant saving them. ## If it doesn't work * Turn Atlas on for that chat before pasting the example prompt. * Tell it which outlet and menu to use. Merchants with several menus need this. Ask it to list your menus, name the one you meant, then run the example prompt again. Ask it to undo the earlier change first. Ask it to refresh from Atlas. Some dashboards hold a snapshot from when they were built. Ask it to read the product back from Atlas and confirm. If they still differ, contact support with the product name. If an example prompt keeps failing, contact support at [hello@atlas.kitchen](mailto:hello@atlas.kitchen) with the prompt you used. ## Next steps Connect Atlas to Claude, ChatGPT, Claude Code or Codex How cross-sell groups work in the Merchant Portal # Set up Atlas in your assistant Source: https://help.atlas.kitchen/connect/mcp/setup Connect Atlas to Claude, ChatGPT, Claude Code or Codex in about two minutes. ## What this does This connects your assistant to your live Atlas data. After it's done, you can ask about sales, edit menus, or 86 an item in plain language. Pick your assistant below and follow the steps to connect Atlas. Go to [Claude connector settings](https://claude.ai/customize/connectors) and select **Add custom connector**. ``` Name: Atlas Remote MCP server URL: https://mcp.atlas.kitchen OAuth Client ID: F-9hyHU9Or0O59Zf9w9pSZ2UHf8Zo9Aoi5oq1CWtV-k Client Secret: leave empty ``` Click **Add**, then select **Connect** on the new Atlas row. Sign in with your Atlas Merchant Portal account, not a personal account. Choose the merchant you want Claude to see, then approve the connection. Start a new chat. Select the **+** button below the message box, then switch on **Atlas**. You only connect once. The connector follows your Claude account, so it works in the browser, the desktop app, the mobile app and Claude Code. Go to [Atlas in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_69fc453d9f388191b28b287ff7624643). One tap, nothing to copy. Follow the prompts to sign in. Choose the merchant you want ChatGPT to see, then approve the connection. Start a new chat and add **Atlas** from the tools menu. Then ask away. ChatGPT reads and writes Atlas data through the chat itself. Its canvases and apps can't call Atlas directly, so you confirm each change in the conversation. Use Claude if you want a dashboard that saves to Atlas as you edit it. If you sign in to Claude Code with the same Claude account, connect Atlas once from [Claude connector settings](https://claude.ai/customize/connectors) and it appears here automatically. Run `/mcp` to check for **claude.ai Atlas**. Otherwise, add it from your terminal: ```bash theme={null} claude mcp add-json --scope user atlas \ '{"type":"http","url":"https://mcp.atlas.kitchen","oauth":{"clientId":"F-9hyHU9Or0O59Zf9w9pSZ2UHf8Zo9Aoi5oq1CWtV-k","callbackPort":48321,"scopes":"mcp"}}' ``` Then run `/mcp`, select Atlas and sign in. Choose a merchant, then approve the connection. Add Atlas to `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.atlas] url = "https://mcp.atlas.kitchen" [mcp_servers.atlas.oauth] client_id = "F-9hyHU9Or0O59Zf9w9pSZ2UHf8Zo9Aoi5oq1CWtV-k" ``` Then sign in: ```bash theme={null} codex mcp login atlas --scopes mcp ``` Codex opens Atlas in your browser. Sign in, choose a merchant, then approve the connection. ## What should happen Ask your assistant: **"Using Atlas, how many orders did we do yesterday?"** You should get a real number from your outlet within a few seconds, not a general answer about restaurants. The assistant shows you when it calls an Atlas tool. ## If it doesn't work * Sign in with your Atlas Merchant Portal account, not a personal account. * Turn Atlas on for that chat. In Claude, select the **+** button and switch on **Atlas**. In ChatGPT, add **Atlas** from the tools menu. * Start the request with "Using Atlas, …" so the assistant reaches for the connector. You picked a different merchant when you signed in. Reconnect and choose the right one — see [Switch merchants](#switch-merchants) below. * Open your connector settings and check Atlas is still connected. Reconnect if it shows an error. * Sign-ins expire. Reconnecting fixes most one-off failures. Refresh the Merchant Portal page. If it's still missing, ask the assistant to read the item back from Atlas. It will tell you whether the change actually saved. If it still doesn't work, contact support at [hello@atlas.kitchen](mailto:hello@atlas.kitchen). Tell us which assistant you used and what you asked for. ## Switch merchants You connect to one merchant at a time. To change: * **Claude:** Reconnect Atlas from [Claude's connector settings](https://claude.ai/customize/connectors) * **ChatGPT:** Reconnect Atlas from ChatGPT's app settings * **Claude Code:** Run `/mcp`, select Atlas, then **Clear authentication**. Sign in again and choose another merchant * **Codex:** Run `codex mcp logout atlas`, then `codex mcp login atlas --scopes mcp`. Sign in again and choose another merchant ## Other clients Any MCP-capable client can connect: | Setting | Value | | - | - | | **URL** | `https://mcp.atlas.kitchen` | | **Transport** | Streamable HTTP | | **Headers** | `X-Api-Key`, `X-Merchant-Id` | Need an API token? Follow the [API authentication guide](/connect/admin-api/authentication). The same token works with the MCP headers above. ## Next steps Copy-paste prompts for costs, allergens, cross-sells and modifiers What your assistant can see and change # Introducing Atlas Connect Source: https://help.atlas.kitchen/connect/overview Atlas Connect is a set of **Open APIs** that expose Atlas application data and functionality to external apps and developers These APIs enable you to build custom ordering experiences and sync data with merchant operations ## APIs Browse menus, manage carts, accept payments, confirm orders Sync menus, create orders, manage users, query inventory ## Common use cases Menu, cart, payment, order confirmation Create orders from custom channels Sections, items, modifiers in a single call # Authentication Source: https://help.atlas.kitchen/connect/storefront-api/authentication ## Channel ID Every request must include an `X-Channel-Id` header. This identifies which merchant's storefront you're accessing — it determines the outlets, menus, branding, and payment configuration the diner sees You receive the channel ID when a merchant is onboarded to Atlas. It is a fixed identifier, not a secret ## Sessions Start by calling `GET /channel` with your channel ID. This creates a session and returns it in the `X-Session-Id` response header ```bash theme={null} curl -sD - https://api.atlas.kitchen/storefronts/v1/channel \ -H "X-Channel-Id: your-channel-id" ``` ``` # Response header — save this X-Session-Id: b7ac755d301dc5d23c790ccd7bb6dadf ``` Include both headers on all subsequent requests: | Header | What it is | Where it comes from | | - | - | - | | `X-Channel-Id` | Merchant's storefront identifier | Provided during onboarding | | `X-Session-Id` | Diner's session (tracks cart) | Returned by `GET /channel` | `GET /channel` is the only endpoint that creates a session. All other endpoints require a valid `X-Session-Id` header — calling them without one returns `401 Unauthorized` Read-only endpoints (menus, stocks, timeslots, availabilities, announcements, banners, popups) work with just `X-Channel-Id` — no session needed ## Session lifecycle A session holds a reference to the diner's active cart. There's always exactly one active cart per session at any time. * **Creation**: the first `GET /channel` call creates a session and returns `X-Session-Id` * **Reuse**: pass the same `X-Session-Id` on subsequent `GET /channel` calls to keep the same session (and cart). Send no session, and a new one is minted * **After checkout**: when `POST /cart/order` succeeds, the session's active cart is marked `is_checked_out: true` and a fresh empty cart is created for the same session. The session ID stays valid — reuse it for the diner's next order Persist `X-Session-Id` in local storage. As long as it's valid, returning diners keep their cart across page reloads. # Add item Source: https://help.atlas.kitchen/connect/storefront-api/cart/add-item post /cart/items Add a menu item with optional modifiers (sub_items). Validates stock and modifier group constraints. # Apply promo Source: https://help.atlas.kitchen/connect/storefront-api/cart/apply-promo put /cart/promo Validates and applies a promotion to the cart. Only one promo per cart. # Clear promo Source: https://help.atlas.kitchen/connect/storefront-api/cart/clear-promo delete /cart/promo # Create cart Source: https://help.atlas.kitchen/connect/storefront-api/cart/create-cart post /cart Creates a new cart for the session or returns the existing active cart. Cart starts without outlet or items. # Delivery outlets Source: https://help.atlas.kitchen/connect/storefront-api/cart/delivery-outlets get /cart/delivery_outlets Only available when cart fulfilment_type is delivery. # Payment breakdown Source: https://help.atlas.kitchen/connect/storefront-api/cart/payment-breakdown get /cart/payment_breakdown Returns itemized charges including subtotal, tax, delivery fee, discounts, service charge, and points value. # Remove item Source: https://help.atlas.kitchen/connect/storefront-api/cart/remove-item delete /cart/items/{id} # Toggle points Source: https://help.atlas.kitchen/connect/storefront-api/cart/toggle-points put /cart/points # Update cart Source: https://help.atlas.kitchen/connect/storefront-api/cart/update-cart patch /cart Set outlet, fulfilment type, timeslot, contact info, delivery address, gifting details. When you set `outlet_id`, the API auto-derives `brand_id` from the outlet's branded `ChannelLink` configuration — you don't need to (and shouldn't) set `brand_id` manually. # Update item Source: https://help.atlas.kitchen/connect/storefront-api/cart/update-item patch /cart/items/{id} Update quantity or notes. Cannot set quantity to 0 — use DELETE instead. # Validate cart Source: https://help.atlas.kitchen/connect/storefront-api/cart/validate-cart post /cart/validation Validates stock, timeslots, minimum order value, etc. Returns a token for duplicate payment prevention. # Get channel Source: https://help.atlas.kitchen/connect/storefront-api/channel/get-channel get /channel Returns merchant config, outlets with service hours, referral program, and point program. Creates a new session if `X-Session-Id` is not provided. # Checkout flow Source: https://help.atlas.kitchen/connect/storefront-api/checkout-flow The complete ordering flow from menu to confirmed order: Checkout Flow ## After payment After creating a payment intent, direct the diner to the `atlas_pay_url` to complete payment. Then poll `POST /cart/order` to confirm: ``` 1. POST /payment_intents → get atlas_pay_url 2. Direct diner to atlas_pay_url 3. Poll POST /cart/order - 422 → payment not yet complete, keep polling - 200 → order confirmed, stop polling ``` `POST /cart/order` validates the payment **in real-time** against the payment processor. It does **not** depend on webhooks * **Payment succeeded** → cart converts to a confirmed order, full order object returned * **Payment not completed** → `422` with `"Insufficient payment made to the cart"` `POST /cart/order` is idempotent — if called after the order is already created, it returns the existing order. Safe to retry # Get availabilities Source: https://help.atlas.kitchen/connect/storefront-api/menu/get-availabilities get /outlets/{outlet_id}/serving_dates/{serving_date}/availabilities Returns hidden/disabled state for sections and items based on timeslot and fulfilment type. # Get menus Source: https://help.atlas.kitchen/connect/storefront-api/menu/get-menus get /outlets/{outlet_id}/serving_dates/{serving_date}/menus Returns published menus with sections, products, and modifier groups. # Get stocks Source: https://help.atlas.kitchen/connect/storefront-api/menu/get-stocks specs/storefront-v1.yaml GET /outlets/{outlet_id}/serving_dates/{serving_date}/stocks Returns available quantity per item for the outlet on the given date. Empty items object means unlimited stock. # Get timeslots Source: https://help.atlas.kitchen/connect/storefront-api/menu/get-timeslots get /outlets/{outlet_id}/serving_dates/{serving_date}/timeslots # Create order Source: https://help.atlas.kitchen/connect/storefront-api/order/create-order post /cart/order **Call this after the diner completes payment and is redirected back.** This endpoint does three things in sequence: 1. Validates the cart (items, timeslot, minimum order, etc.) 2. Checks payment status **in real-time** against the payment processor (does NOT depend on webhooks — makes a synchronous call to verify) 3. If fully paid, converts the cart to a confirmed order Returns the full order object on success, or `422` with specific errors if the cart is invalid or payment hasn't completed yet. If the order was already created (e.g. duplicate call), returns the existing order. After success, the session automatically gets a new empty cart. # Create payment intent Source: https://help.atlas.kitchen/connect/storefront-api/payment/create-payment-intent post /payment_intents Validates the cart and creates a payment intent with the payment processor. Returns an `atlas_pay_url` — redirect the diner there to complete payment. If a pending intent already exists for the same amount, it is returned instead of creating a duplicate. **After payment:** Once the diner completes payment on the hosted page, they are redirected back to your application. At that point, call `POST /cart/order` to validate the payment and convert the cart to an order. Do NOT wait for webhooks — `POST /cart/order` checks payment status in real-time. # Cart events Source: https://help.atlas.kitchen/connect/webhooks/cart-events Cart webhook payloads. Cart events describe a POS dine-in cart during service, before the bill is paid. Cart event money fields are sent as decimal major currency units for most currencies. For example, Singapore dollars are sent as dollars, not cents. ## Event types | Event type | Trigger | | - | - | | `cart.items_fired` | Staff send items to the kitchen on a POS dine-in cart. | | `cart.archived` | A POS cart is archived. | ## `cart.items_fired` payload Each payload carries the full current state of the cart, not a delta. The latest payload replaces everything you stored from earlier ones, so a missed delivery is healed by the next one. This event fires only for staff-attended POS carts. Self-service carts (QR ordering, kiosk, online) do not fire it. A cart whose order has closed stops firing. ```json theme={null} { "id": 48213, "status": "open", "identifier": "P48213", "fulfilment_type": "dine_in", "notes": "Birthday table", "pax": 4, "subtotal": 44.5, "total_including_tax": 48.51, "reservation_id": "resv-8zk2fm", "outlet": { "id": 31, "name": "Atlas Cafe Raffles Place" }, "user": null, "table": { "id": 512, "outlet_id": 31, "name": "A4", "created_at": 1749794130, "updated_at": 1749794130 }, "cart_items": [ { "id": 991, "item_id": 1204, "item_sku": "laksa-classic", "name": "Laksa", "quantity": 2, "currency": "SGD", "unit_price": 18, "item_total": 36, "type": "Product", "status": "sent", "voided": false, "sub_items": [ { "id": 992, "item_id": 1310, "item_sku": "extra-cockles", "name": "Extra cockles", "quantity": 1, "currency": "SGD", "unit_price": 2, "item_total": 2, "type": "Product", "status": "sent", "voided": false, "sub_items": [] } ] }, { "id": 995, "item_id": 1287, "item_sku": "kaya-toast", "name": "Kaya toast", "quantity": 1, "currency": "SGD", "unit_price": 6.5, "item_total": 6.5, "type": "Product", "status": "held", "voided": false, "sub_items": [] } ] } ``` | Field | Type | Description | | - | - | - | | `id` | integer | Cart ID. Equals `cart_id` on the [order payload](/connect/webhooks/order-events) for the same visit. | | `status` | string | `open` while the bill is unpaid. Cart events stop once the order closes. | | `identifier` | string | Human-readable check reference. Matches the order payload's `identifier` once an order exists. | | `fulfilment_type` | string | Fulfilment type of the cart, such as `dine_in`. | | `notes` | string \| null | Cart notes entered by staff. | | `pax` | integer \| null | Party size. | | `subtotal` | number | Running subtotal of the current items. | | `total_including_tax` | number | Running total including tax. Final amounts arrive on the closing order event. | | `reservation_id` | string \| null | External reservation reference, when the cart came from a reservation. | | `outlet` | object \| null | The outlet the cart belongs to: `id` and `name`. | | `user` | object \| null | Customer identity when known: `id`, `name`, and `external_user_links`. Often `null` before payment — do not key on it. | | `table` | object \| null | The table the cart is open on. | | `cart_items` | array | Every current top-level item. See below. | `cart_items[].status` is `sent` once the item has been fired to the kitchen, or `held` while it waits. `voided: true` marks a removed item. `sub_items` nests modifiers, using the same fields as a top-level item. ### Handling deliveries Delivery is at-least-once and unordered. Payloads carry no ordering token. Apply these rules: 1. Match cart events and [order events](/connect/webhooks/order-events) for the same visit on the cart `id`. It equals the order payload's `cart_id`. 2. Treat each payload as the full cart state. Replace what you stored for that cart. A stale or duplicate delivery is corrected by the next kitchen send. 3. Discard `status: "open"` payloads for a cart whose closing order event you have already processed. ## `cart.archived` payload ```json theme={null} { "cart_id": 12345, "is_archived": true } ``` # Customer events Source: https://help.atlas.kitchen/connect/webhooks/customer-events Customer webhook payloads. ## Event types | Event type | Trigger | | - | - | | `user.created` | A non-guest, non-system user is created. | | `user.updated` | A non-guest, non-system user is updated. | Atlas does not send `user.created` or `user.updated` for guest users or system users. ## Payload ```json theme={null} { "id": 321, "email": "jane@example.com", "mobile_number": "+6591234567", "name": "Jane Tan", "date_of_birth": "1990-01-01", "marketing_consent": true, "title": "Ms", "external_user_links": [ { "external_user_id": "customer-123", "external_user_type": "loyalty_integration" } ] } ``` # Events Source: https://help.atlas.kitchen/connect/webhooks/events Event payloads sent by Atlas Connect webhooks. Events let your system react when something changes in Atlas. When a subscribed event occurs, Atlas creates an event payload and sends it to your configured webhook URL. ## Event payload ```json theme={null} { "id": "6f2b65d9-54dc-4c1d-a7da-71f0d7b6a10a", "event_type": "order.created", "data": {}, "created_at": "2026-06-18T10:15:30.000+08:00", "updated_at": "2026-06-18T10:15:30.000+08:00" } ``` | Attribute | Type | Description | | - | - | - | | `id` | string | Unique event ID. Store this to prevent duplicate processing. | | `event_type` | string | The event that occurred, such as `order.created`. Use this to route webhook handling. | | `data` | object | Event-specific data. | | `created_at` | string | Time when Atlas created the event payload. | | `updated_at` | string | Time when Atlas last updated the event payload. | ## Event types | Event type | Trigger | `data` payload | | - | - | - | | `order.created` | An order is created. | [Order payload](/connect/webhooks/order-events) | | `order.updated` | An order is updated. | [Order payload](/connect/webhooks/order-events) | | `order.cancelled` | An order changes to `cancelled`. | [Order payload](/connect/webhooks/order-events) | | `order.confirmed` | An order changes to `confirmed`. | [Order payload](/connect/webhooks/order-events) | | `order.completed` | An order changes to `completed`. | [Order payload](/connect/webhooks/order-events) | | `order.dispatched` | An order changes to `dispatched`. | [Order payload](/connect/webhooks/order-events) | | `user.created` | A non-guest, non-system user is created. | [Customer payload](/connect/webhooks/customer-events) | | `user.updated` | A non-guest, non-system user is updated. | [Customer payload](/connect/webhooks/customer-events) | | `outlet.created` | An outlet is created. | [Outlet payload](/connect/webhooks/outlet-events) | | `outlet.updated` | An outlet is updated. | [Outlet payload](/connect/webhooks/outlet-events) | | `stock.updated` | Item availability changes for an outlet. | [Stock payload](/connect/webhooks/stock-events) | | `cart.items_fired` | Staff send items to the kitchen on a POS dine-in cart. | [Cart payload](/connect/webhooks/cart-events) | | `cart.archived` | A POS cart is archived. | [Cart payload](/connect/webhooks/cart-events) | | `menu.updated` | A menu is updated. | [Menu payload](/connect/webhooks/menu-events) | # Menu events Source: https://help.atlas.kitchen/connect/webhooks/menu-events Menu webhook payloads. ## Event types | Event type | Trigger | | - | - | | `menu.updated` | A menu is updated. | ## Payload ```json theme={null} { "event": "menu.updated", "menu_id": 789 } ``` Atlas sends only the menu ID for `menu.updated`. Fetch the full menu through the Admin API if your system needs the updated menu hierarchy. # Order events Source: https://help.atlas.kitchen/connect/webhooks/order-events Order webhook payloads. Order events use the same `data` shape. Order event money fields are sent as decimal major currency units for most currencies. For example, Singapore dollars are sent as dollars, not cents. ## Event types | Event type | Trigger | | - | - | | `order.created` | An order is created. | | `order.updated` | An order is updated. | | `order.cancelled` | An order changes to `cancelled`. | | `order.confirmed` | An order changes to `confirmed`. | | `order.completed` | An order changes to `completed`. | | `order.dispatched` | An order changes to `dispatched`. | ## Payload ```json theme={null} { "order_id": 98765, "id": 98765, "cart_id": 48213, "identifier": "A123", "state": "confirmed", "serving_date": "2026-06-18", "subtotal": 28.5, "surcharge": 0, "delivery_fee": 4, "discount": 0, "admin_discount": 0, "total": 32.5, "tax": 2.92, "total_including_tax": 35.42, "created_at": "2026-06-18T10:15:30+08:00", "cancelled_at": null, "completed_at": null, "promotion_level": null, "barcode_identifier": "ATLAS123456", "donation": 0, "contact_name": "Jane Tan", "fulfilment_type": "delivery", "timeslot_range": "12:00 PM - 12:30 PM", "table": { "id": 12, "name": "T12" }, "user": { "id": 321, "email": "jane@example.com", "mobile_number": "+6591234567", "external_id": "customer-123" }, "outlet": { "id": 45, "label": "Atlas Cafe", "description": "Main outlet", "address": "1 Example Street", "archived": false }, "promotion": { "id": 10, "label": "Lunch promo", "type": "Promotion", "description": "Lunch discount", "code": "LUNCH" }, "order_source": { "id": 7, "source_label": "website", "source_type": "Website" }, "payment_type": { "id": 3, "label": "Credit Card" }, "order_items": [ { "id": 111, "item_id": 222, "item_sku": "SKU-001", "order_item_id": null, "modifier_id": null, "name": "Chicken bowl", "quantity": 1, "currency": "SGD", "unit_price": 12.5, "unit_modifier_price": 2, "unit_component_price": 0, "type": "Product", "order_id": 98765, "barcode_identifier": "ATLAS123456", "item_total": 14.5, "item_discount": 0, "tags": ["lunch"], "product_tags": ["lunch"], "kitchen_tags": ["hot"], "report_category": "Mains", "voided": false, "brand": { "id": 55, "label": "Atlas Cafe", "description": "All-day dining" }, "sections": [ { "id": 66, "label": "Bowls", "description": "Rice and salad bowls" } ], "sub_items": [ { "id": 112, "item_id": 223, "item_sku": "SKU-001-MOD", "order_item_id": 111, "modifier_id": 333, "name": "Add avocado", "quantity": 1, "currency": "SGD", "unit_price": 2, "unit_modifier_price": 0, "unit_component_price": 0, "type": "Product", "order_id": 98765, "barcode_identifier": "ATLAS123456", "item_total": 2, "item_discount": 0, "tags": ["addon"], "product_tags": ["addon"], "kitchen_tags": [], "report_category": "Modifiers", "voided": false, "brand": { "id": 55, "label": "Atlas Cafe", "description": "All-day dining" }, "sections": [], "sub_items": [] } ] } ] } ``` `cart_id` is the cart the order was created from. It is `null` when the order has no cart. It equals `id` on [cart events](/connect/webhooks/cart-events) for the same visit, so both event streams resolve to one check. `order_items` contains top-level items only. `sub_items` contains modifiers and nested components attached to a parent item. A sub-item uses the same fields as a top-level order item. The `order_item_id` field points to the parent order item, and `modifier_id` is present when the sub-item came from a modifier. # Outlet events Source: https://help.atlas.kitchen/connect/webhooks/outlet-events Outlet webhook payloads. ## Event types | Event type | Trigger | | - | - | | `outlet.created` | An outlet is created. | | `outlet.updated` | An outlet is updated. | ## Payload ```json theme={null} { "id": 45, "identifier": "main-outlet", "label": "Atlas Cafe", "address": "1 Example Street", "description": "Main outlet", "contact_number": "+6561234567", "created_at": "2026-06-18T10:00:00.000+08:00", "updated_at": "2026-06-18T10:15:30.000+08:00", "email": "outlet@example.com", "archived": false } ``` # Set up webhooks Source: https://help.atlas.kitchen/connect/webhooks/setup Add an Atlas Connect webhook endpoint. Atlas sends selected events to an HTTPS endpoint that you control. ## Add a webhook Admins can manage webhook endpoints in the [Atlas Merchant Portal](https://portal.atlas.kitchen/atlas-connect/webhooks). 1. Go to **Atlas Connect > Webhooks**. 2. Click **Add webhook**. 3. Enter a **Name**. 4. Enter an **Endpoint URL**. The URL must start with `https://`. 5. Choose whether the webhook is **Enabled**. 6. Select the **Events** this endpoint should receive. 7. Choose **Authentication**: * **Bearer token** — Atlas sends `Authorization: Bearer `. * **Custom header** — Atlas sends the header name and value you provide. 8. Save the webhook. Disabled webhooks stay saved but do not receive events until re-enabled. Secrets are stored for delivery and are not shown again after saving. ## Delivery Atlas sends a `POST` request with a JSON event payload. Return any `2xx` response to acknowledge receipt. Process events idempotently. Atlas queues webhook delivery asynchronously, and your endpoint may receive the same event more than once. # Stock events Source: https://help.atlas.kitchen/connect/webhooks/stock-events Stock webhook payloads. ## Event types | Event type | Trigger | | - | - | | `stock.updated` | Item availability changes for an outlet. | Atlas sends `stock.updated` when item availability changes for an outlet. It can also be sent when an order sells out an item and Atlas marks the item unavailable. ## Payload ```json theme={null} { "item_id": 222, "outlet_id": 45, "is_available": false } ``` # Update diners' phone number Source: https://help.atlas.kitchen/customer-guides/diners-phone-update Guide for diners to update phone numbers on Atlas Online. Log in, recover access via email, update profile details, and verify changes. **Who is this article for?** * Customers that have an Atlas ID account on your restaurant's Atlas Online website. ## Updating a phone number on the restaurant's website Customers can follow these steps to update their phone number: 1. **Log in to the restaurant's website:** Atlas Online website header showing user icon in top-right corner with Log In option * Click the **user icon** in the top-right corner. * Click **Log in**. 2. **Enter login credentials:** * On the **Log in** page, enter the registered email address. * Click **Log in**. 3. **Recover access if the phone number is unavailable:** Login verification screen showing Send code to email instead option for customers without phone access * If access to the registered phone number is lost, select **Send code to email instead**. * Enter the access code received via email. 4. **Navigate to the profile page:** Atlas Online user menu dropdown showing Profile option to access account settings and update information * After logging in, the page will redirect to the **landing page**. * Click the **user icon** in the top-right corner. * Select **Profile**. 5. **Update the phone number:** * Click the **Mobile number** field. * Enter the new phone number. * Click **Update your profile**. 6. **Verify the update:** * The phone number should now be updated. * If any issues persist, diners can email [**hello@atlas.kitchen**](mailto:hello@atlas.kitchen) for further assistance. # Install Atlas Merchant Portal Source: https://help.atlas.kitchen/get-started/installing-atlas Add Atlas Merchant Portal as a home screen shortcut on your tablet for faster access. Works on Chrome and Safari browsers. Atlas Merchant Portal can be accessed from any device at [https://portal.atlas.kitchen](https://portal.atlas.kitchen) and a valid login. For the best experience on your tablet, install an Atlas screen shortcut on your device: 1. Open Atlas Merchant Portal ([https://portal.atlas.kitchen](https://portal.atlas.kitchen)) in Google Chrome or Safari. 2. Tap the menu icon (three dots on Chrome, share button on Safari). Browser menu showing Add to Home Screen option in Chrome three-dot menu and Safari share sheet 3. Select "Add to Home Screen". 4. Rename it to Atlas and tap Add. Add to Home Screen dialog with Atlas name field and Add button to create home screen shortcut 5. Open the new desktop app, and log in with your credentials. ## What should happen After completing the steps above: * An "Atlas" icon appears on your device's home screen * Tapping the icon opens Atlas Merchant Portal in a standalone app window (no browser toolbar) * You can log in with your existing Atlas credentials * The app works just like the browser version but launches faster ## If it doesn't work 1. Make sure you're using Chrome (Android) or Safari (iOS) — other browsers may not support this feature 2. On Chrome: Tap the three-dot menu, then scroll down to find "Add to Home Screen" 3. On Safari: Tap the share icon (square with arrow), then scroll down to "Add to Home Screen" 4. On some devices, this option appears as "Install app" instead 1. Check your home screen pages — the icon may be on a different page 2. Check your app drawer or library (Android) 3. Try adding again — sometimes the first attempt fails silently 4. Restart your device and try again 1. Check your internet connection 2. Clear the app cache: Delete the shortcut, clear browser cache, and add again 3. Try logging in through the regular browser first to confirm your account works 1. Check that you're using the correct email and password 2. Try logging in through the browser version first 3. If you forgot your password, use "Forgot password" on the login page 4. Contact support at [hello@atlas.kitchen](mailto:hello@atlas.kitchen) if you're locked out ## Next steps * [Set up your outlet](/merchant-portal/operating-hours) — Configure your restaurant hours * [Connect your printer](/hardware/printers) — Set up receipt printing * [Explore the dashboard](https://portal.atlas.kitchen) — Start using Atlas Merchant Portal # Onboarding process Source: https://help.atlas.kitchen/get-started/onboarding Get started with Atlas onboarding. Learn the setup process, hardware requirements, WiFi specs, and best practices for a smooth restaurant launch. **Who is this article for?** * New restaurants in the process of onboarding Atlas. Getting started with Atlas is simple. We handle the heavy lifting so you can focus on running your business. From setting up menus to installing hardware, we take care of the details, and let you focus on what matters - your restaurant launch. Here's a general breakdown on the Atlas onboarding process: 1. **Gathering information**. We collect the necessary details to configure your Atlas setup. 2. **Designing and confirming ordering flows**. We'll work with you to make sure the setup matches your operations. 3. **Getting Atlas ready.** We take care of this while you prepare for launch (this includes menus, diner-interface websites design, setting up products, operating hours, etc.). 4. **Installation and training.** We meet you in person to set up hardware, test it, and train your team. This usually happens within the same day, a few days before your launch. 5. **Go-live**. Once everything is in place, you're ready to start taking orders. Ensure your onboarder knows this date so they can be on standby to provide support. 6. **Account management.** We will keep ironing out the details after you go live. Some of our plans might not work, so we will use this week to keep training you and calibrating ops. ### What hardware to buy Atlas runs smoothly on most modern tablets, but these are some recommendations based on our experience. If you have any doubts, it's best to install Atlas on your tablet to see if it performs well. Minimum specs: * Android 10+ or iPadOS 14+ * 4GB RAM * Quad-core processor * 32GB storage Recommended tablets: * Android -> Xiaomi Pad Pro or similar specs * iOS -> iPad 9th Gen or newer ### Importance of WiFi Atlas is a cloud-based system accessed from a browser, so it requires a strong, stable WiFi connection to run smoothly. We recommend using business-grade routers like Ubiquiti UniFi Dream Machine UDM-US or ASUS ZenWiFi AX (XT8) for the best performance. If you prefer to source your own, this is some of the criteria to consider: * Strong antenna and good range. Your router should provide at least 30m of range, assuming signal loss through one wall. * Dual-band or tri-band with WiFi 6. Ensures better load management and future-proofing. * Must have 2.4GHz support. Best for receipt printer compatibility. * Handles multiple devices. Should support 16-32 connected clients. * Nice to have: Dual WAN and/or 4G backup support. Helps maintain connectivity if one network fails. If possible, avoid 4G-based routers. They tend to have slower speeds and a limited number of supported devices. Low-spec home routers may also have limitations and struggle to handle multiple devices, potentially causing lag. Atlas printers can connect to your network via wireless WiFi and LAN cable. We recommend using a LAN cable connected to your main network, and wireless connection with your back up network. # Set up Atlas to earn more Source: https://help.atlas.kitchen/get-started/sell-more Boost restaurant revenue with aggregator integrations, loyalty rewards, cross-selling, and menu engineering best practices in Atlas. **Who is this article for?** * New restaurants in the process of onboarding Atlas. * Existing Atlas merchants that want to optimise their setup and menus to sell more. * To access all the features mentioned you need Admin permissions. Set permissions from **Settings > Team members**. Atlas is more than just an operating system — it's a tool to grow your revenue. With the proper setup, Atlas will help you increase sales, give your customers a better experience, and keep them coming back. ## Leverage Atlas to earn more Here are a few best practices we have noticed not to leave money on the table: * **Make sure you're listed on Foodpanda, GrabFood, and Deliveroo aggregators.** Atlas Aggregator lets you manage all these platforms in one place. More platforms > more visibility > more customers that get to know you. * **Redirect customers to order directly from you.** Now that your customers know you, encourage them to order through Atlas Online instead of aggregators to save on commission fees. Offer exclusive discounts for your website, exclusive bundles, loyalty rewards, etc. * **Keep customers coming back with loyalty rewards.** Atlas Loyalty makes repeat visits more likely with points-based rewards, targeted promotions, marketing campaigns, EDM blasts, and exclusive discounts for regulars. * **Use cross-selling features to increase order value.** Customers are already ordering, so help them add more with smart suggestions. Set cross-selling groups in Scan to Order, Kiosk, and Online from the beginning and iterate to perfect them. * **Design menus that encourage more spending.** We will break this down in the following next section. Atlas helps you sell more, earn more, and keep customers coming back — make sure you're using it to its full potential. If you need help understanding how to do this, please contact us in our dedicated WhatsApp group. ## Set up your menus for success Menu engineering is about structuring your menu to drive higher spending. With Atlas, you have powerful tools to increase your Average Order Value (AOV) while making it seamless for customers to order more. Here are some best practices we've noticed: * **Highlight high-margin items in Atlas Scan to Order, Kiosk and Online.** Re-arrange products on your menu to feature best-sellers, chef's specials, and high-margin dishes at the top of your sections. You can explore adding “Recommended” promotional labels to guide customer choices. * **Descriptions & photos are essential.** Instead of “Spaghetti with tomato sauce,” try “Slow-simmered tomato sauce over hand-crafted pasta.” Adding pictures to Atlas Online and Kiosk can boost sales by up to 30%. * **Create combos and bundles.** Increase AOV by offering meal deals. You can create easy-to-add combos (e.g. burger + fries + drink) at a slightly discounted rate, increasing overall spend while giving customers value. Make sure to create delivery bundles that also serve a specific number of pax. * **Create modifier groups to upsell.** With Atlas Kiosk and Scan to Order, customers should always see suggestions for add-ons, sides, or drinks when adding products. * **Optimise pricing presentation.** Set up your more pricey and premium items or choices first to anchor prices. If you want to implement any of these and don't know how, please contact us in our dedicated WhatsApp group. to get things started. # Using SMS with Atlas and Customer.io Source: https://help.atlas.kitchen/guides/sms-with-customerio Connect your own Twilio sender to Customer.io to send loyalty SMS, order confirmations, and one-time passcodes to your customers. **Who is this for?** * Atlas merchants who use Customer.io for marketing * Merchants who want to reach customers by SMS ## What this does This connects your Twilio account to Customer.io. Your customers receive SMS messages sent from your own Twilio sender. Use this for loyalty messages, order confirmations, and one-time passcodes. ## When to use this * You want to send loyalty SMS to customers who have opted in * You need to send order confirmations or one-time passcodes by text * You are setting up or already have a Twilio account ## Steps Go to [twilio.com](https://www.twilio.com/en-us) and sign up for a paid account. Once your account is active, buy a sender. You have two options: * **Phone number**: Buy a local number from Twilio. * **Alphanumeric Sender ID**: Use your brand name as the sender (for example, `ATLAS`). Not available in all countries. **Singapore merchants using an Alphanumeric Sender ID**: You must register your sender ID with the SGNIC SMS Sender ID Registry (SSIR) before sending. Without registration, your messages may appear as "Likely-SCAM" on recipients' phones. Register at [sgnic.sg/faq/sms-sender-id-registry](https://www.sgnic.sg/faq/sms-sender-id-registry). In the Twilio Console, go to your account settings and copy your **live** Account SID and Auth Token. Do not use test credentials — they do not send real messages. In Customer.io, go to **Workspace Settings**, then click **SMS**. Enter your Twilio credentials in the fields provided: ```plaintext theme={null} Account SID: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Auth Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` Enter your sender phone number or Alphanumeric Sender ID. Click **Save**. Choose how you want to send SMS in Customer.io: * **Campaign workflow**: Drag an SMS action into a workflow. Use this for automated loyalty messages triggered by a customer action. * **SMS newsletter**: Create a one-time broadcast to a segment of customers. Use this for promotions and announcements. * **Transactional SMS**: Send order confirmations or one-time passcodes. Use this for time-sensitive messages. ## What should happen * Customers receive SMS messages from your Twilio sender. * Loyalty messages arrive within seconds of being triggered in Customer.io. * Customer.io shows a delivery status for each message sent. ## If it doesn't work 1. Check that you entered your **live** Account SID and Auth Token. Test credentials do not send real messages. 2. Confirm your Twilio account is paid and active, not on a trial. 3. Open the Twilio Console and check for error codes on failed messages. 4. Make sure your sender number or Alphanumeric Sender ID is active in Twilio. Register your Alphanumeric Sender ID with the SGNIC SMS Sender ID Registry before sending. See Step 1 above for the registration link. 1. Confirm customers have opted in to SMS communications. 2. Check that each customer's phone number includes the correct country code. 3. Review the delivery log in Customer.io for failed deliveries. If the issue persists, contact support at [hello@atlas.kitchen](mailto:hello@atlas.kitchen). ## What's next * [Set up your loyalty programme](/merchant-portal/loyalty-signup) * [Manage your customer data](/merchant-portal/customers-data) # Connect Atlas printer to WiFi Source: https://help.atlas.kitchen/hardware/printers Connect Atlas receipt printers to WiFi network. Choose manual browser pairing or QR pairing with WeChat for wireless printer setup. Atlas printers can be connected to WiFi wirelessly using one of these two methods: * Mode A: QR pairing with WeChat. * Mode B: Manual pairing via browser (recommended). Follow these steps to pair your printer using WeChat: 1. Connect to the outlet's WiFi network (must be 2.4GHz). 2. Download WeChat and create an account. 3. Locate the small black button at the back of the printer. 4. Press and hold the button for 2 seconds and release → A receipt will print. 5. Repeat step 4 → A receipt will print with a QR code. 6. Open WeChat and scan the QR code. * Note: This connects the printer to WiFi. 7. Enter your WiFi password and confirm. * Note: Ensure Bluetooth and Local Network access are enabled if needed. 8. On the next screen, select the Printer network and tap Connect. 9. Wait for the printer to connect and print a success receipt. 10. If the connection failed receipt prints, repeat the steps or check your WiFi stability. Atlas receipt printer showing small black pairing button location at the back of the device Printer configuration receipt showing Mode A and Mode B pairing options after first button press This enters Mode B: Manual WiFi pairing mode (lasts 5-10 minutes) Printer receipt confirming Mode B manual WiFi pairing mode is active with instructions Wait until your device is connected. This network has no internet access, but that's fine for this setup. Device WiFi settings showing Printer network in available networks list for connection Printer configuration login prompt requesting admin username and password for access You can change the language (Mandarin or English) from the top-right corner. Printer configuration interface showing SCAN button in top-right corner to detect available WiFi networks Printer WiFi network selection screen displaying list of available networks with radio buttons and OK button A prompt saying the password is empty will come up. Just press ok, and move to the next step. Printer WiFi password entry screen with password field, Show Password checkbox, and Save button Printer configuration confirmation screen with Restart button to finalise WiFi connection setup Within a few minutes, a successful connection receipt should print. *This may take up to 10 minutes in some cases.* If a connection failed receipt prints instead, go through the guide again and ensure all steps were followed correctly. Also, check your WiFi stability. ## What should happen After completing the WiFi setup: * The printer prints a "Connection Successful" receipt showing it's connected to your WiFi network * The printer appears in Atlas Merchant Portal under your outlet's printer settings * You can send test prints from Atlas POS or the Merchant Portal ## If it doesn't work 1. Verify your WiFi password is correct — re-enter it carefully 2. Check that your WiFi network is 2.4GHz (not 5GHz) — the printer only supports 2.4GHz 3. Move the printer closer to your WiFi router 4. Check if your WiFi network has a captive portal (login page) — the printer cannot connect to networks requiring browser login 5. Restart your WiFi router and try again 1. Make sure you're in Mode B (manual pairing mode) — press and hold the button until the second receipt prints 2. The printer's WiFi mode only lasts 5-10 minutes. If it timed out, press the button again to re-enter pairing mode 3. Check that your phone/tablet WiFi is turned on 4. If "Printer" doesn't appear in your WiFi list, restart the printer and try again 1. Make sure you're connected to the "Printer" WiFi network (not your regular WiFi) 2. Wait 10-15 seconds after connecting before opening the browser 3. Type the address exactly: `10.10.100.254` — no "http\://" or "www" 4. Try a different browser if the first one doesn't work 5. Disable any VPN on your device 1. Try lowercase `admin` for both username and password 2. If the printer was previously configured, it may have a different password. Factory reset the printer and try again 3. Check your printer documentation for default credentials 1. Wait 10-15 seconds and tap SCAN again 2. Check that your WiFi router is powered on and broadcasting 3. Move the printer closer to the router 4. Your WiFi may be set to "hidden" — you'll need to enter the network name manually 1. In Atlas Merchant Portal, go to **Settings > Printers** and verify the printer is listed 2. Check that the printer is assigned to the correct outlet and station 3. Send a test print from Atlas to verify the connection 4. Restart the printer and check if it reconnects 5. Contact support at [hello@atlas.kitchen](mailto:hello@atlas.kitchen) if the printer still doesn't appear ## Next steps * [Set up Atlas POS](/get-started/installing-atlas) — Install Atlas on your tablet * [Configure your outlet](/merchant-portal/operating-hours) — Set operating hours and menu * [Start taking orders](/merchant-portal/admin-orders) — Create your first order # Troubleshooting Atlas Pay terminals Source: https://help.atlas.kitchen/hardware/terminal-troubleshooting Fix an Atlas Pay card terminal that is frozen, not showing the payment amount, or has lost connection to the POS. **Who is this article for?** * Atlas merchants using an Atlas Pay card terminal. * Staff taking payments at the counter or kiosk. Atlas Pay card terminals occasionally lose connection, freeze, or fail to show the payment amount. This guide is organised by the problem you are seeing. Find your issue below and work through the fixes in order. ## The terminal won't connect or show the payment amount If the terminal shows "no signal", nothing appears when you tap Charge, or you see **"Error occurred while initiating payment"**, work through these in order. Atlas POS Pick a payment modal showing an 'Error occurred while initiating payment' dialog that advises to try again, restart the payment terminal, then contact support. The error is often a one-off. Re-select the payment method and tap **Charge** again. If it keeps happening, the cause is usually WiFi instability. The terminal has a built-in 4G backup that is more reliable during service. Press and hold the power button on the side of the terminal until the power options appear, then tap **Restart**. Once it is back on the home screen, close and reopen the Atlas POS app on the tablet, then try the charge again. Create a small test order, tap **Charge**, select **Credit Card**, and confirm the amount appears on the terminal. Take payment with a manual method for now, then contact support (see [The terminal is faulty or won't power on](#the-terminal-is-faulty-or-wont-power-on)). **What should happen:** the terminal displays the order amount and is ready for the customer to tap, insert, or scan. ## The customer paid but the order didn't complete If the terminal or POS dropped connection mid-payment, the customer's card may have gone through while the order stays open on the POS. Before charging again, confirm whether the payment actually went through. ### Check the payment on the terminal