Atlas

Create a storefront landing page banner for Atlas-owned ordering channels such as Online, Kiosk, and Scan-to-Order. Do not use this for third-party aggregator apps. Empty or omitted `outlet_ids` targets all accessible outlets. `storefront_id` targets one storefront. Omit `storefront_id` for a merchant-wide banner; for outlet-scoped accounts, omission is only allowed when the account can access exactly one storefront. If no dates are supplied, the banner starts immediately and ends one month later. It defaults to active with a centered desktop layout. This tool uploads and attaches supplied images; it does not generate images. For banner artwork, pass `desktop_image_file`, `mobile_image_file`, or `logo_image_file`, the matching `*_image_url`, or the matching `*_image_base64`. Not idempotent: re-running creates another banner.

Create a menu section, attach it to a menu, and optionally attach existing products or a section image. Omit `parent_section_id` for a top-level section; provide it for a sub-section under an existing section in the same menu. Pass `product_ids` to attach existing products only. To add brand-new products to the section, first create the section, then call `create_product` with `menu_id` and the returned section ID. For a section image, pass `image_file` for a client file attachment, `image_url`, or `image_base64`. The tool stores the image in Atlas before attaching it to the section. Not idempotent: re-running creates another section.

Create a storefront popup for Atlas-owned ordering channels such as Online, Kiosk, and Scan-to-Order. Do not use this for third-party aggregator apps. Empty or omitted `outlet_ids` and `storefront_ids` target all accessible outlets and storefronts. If no dates are supplied, the popup starts immediately and ends one month later. It defaults to active, all users, page-arrival trigger, and every visit. This tool uploads and attaches supplied images; it does not generate images. For popup artwork, pass `desktop_image_file` or `mobile_image_file`, the matching `*_image_url`, or the matching `*_image_base64`. For CTA buttons, pass `button_text` and `button_url`. When `button_url` is present and `button_action` is omitted, the button action defaults to `link_to_url`. Not idempotent: re-running creates another popup.

Create a new POS layout, either blank or as a deep copy of an existing layout. For substantial changes, pass source_pos_layout_id to preserve the original and edit the copy. Omit source_pos_layout_id only when the merchant explicitly wants a blank layout.

Create a new product with its full menu structure: section linkage, modifier groups (existing or new), and modifiers within new groups. Each `modifier_groups[]` entry is either: - `{ id: <int>, ... }` - link an existing modifier group with optional per-link overrides (selection_required_min/max, is_fixed, display_order) - `{ name: <str>, modifiers: [...], ... }` - create a new modifier group and its modifiers Each `modifiers[]` entry is either: - `{ item_id: <int>, ... }` - link an existing product or component as a modifier choice - `{ name: <str>, price_cents: <int>, ... }` - create a new modifier item inline Inline modifier items default to products. Use `type: "component"` only for component modifier choices, typically when the merchant gives unit details like per_unit_quantity/unit_label (for example 100 g salmon). Products created by this tool are always top-level products. Not idempotent: re-running creates a duplicate product (no SKU dedup). Confirm intent before retrying. To change an existing product use `update_product`; browse products with `list_products`. Convert prices to minor units before calling: 12.50 in the merchant currency means price_cents=1250. This tool can link a brand-new product to one section when section_id is provided. Pass menu_id with section_id when the user names a target menu, so the tool can verify the section belongs to that menu. It cannot move existing products between sections. To create a product with an image, pass `image_file` for a client file attachment, `image_url`, or `image_base64`. The tool stores the image in Atlas before attaching it to the product. If the user gives explicit section_id, brand_id, existing modifier-group IDs, or item_id values, pass them directly; do not call `list_menus`, `list_menu_sections`, or `list_products` first just to verify them.

Create a reporting category or subcategory for grouping products in reports. Use this when the merchant wants to add a new report category. Use `list_reporting_categories` to find existing category IDs, and `update_reporting_category` to rename or move an existing category. Pass `parent_id` to create a subcategory under an existing top-level category. Reporting categories support two levels only; a subcategory cannot be used as the parent for another category. Default create is not idempotent: retrying after success usually returns a duplicate-name error because names are unique within the same parent. Pass `upsert: true` only for "ensure this category exists" flows; then an existing name + parent match is returned and `display_order` is ignored.

Create a general order surcharge for a brand/storefront over a calendar-day range. Use this for public holiday, weekend, delivery-only, pickup, dine-in, temporary, or ongoing surcharges. This tool is not holiday-specific: calculate or confirm the dates first, then create surcharge ranges for those dates. value_type 'fractional': value is currency minor units (500 = $5.00). value_type 'percent': value is the percentage number (10 = 10%). fulfilment_types defaults to all fulfilment types; pass ['delivery'] for delivery-only surcharges. Pass outlet_id only when the surcharge should apply to one outlet; omit it for all outlets on the brand/storefront. start_date and end_date are merchant-local calendar dates. The underlying surcharge range is normalized to the beginning/end of those days. Omit end_date for an ongoing surcharge. This tool is idempotent for exact matches: retrying the same brand/date/value/label/fulfilment configuration returns the existing surcharge instead of creating a duplicate.

Manually credit loyalty points to one customer in a specific brand point program. Use this for goodwill, support remediation, or backoffice corrections. Not for points earned from orders (those should flow through the normal checkout/award path), and not for balance lookup — use `get_customer_rewards_balance`. If you do not know the brand_id or point_program_id, use `list_reward_programs`.

Manually deduct loyalty points from one customer in a specific brand point program. Use this for support corrections only. This tool refuses to overdraft a balance; if the customer has fewer points than requested, it returns an error instead of forcing the debit. Not for checkout redemption flows — those should use the normal order/points path. If you do not know the brand_id or point_program_id, use `list_reward_programs`.

Delete one scheduled special-hours record by `special_hours_id`. Use this when the merchant asks to remove a holiday/custom-hours override, undo a one-off closure, or clear special hours for a date range. Call `get_outlet` first when the user gives only an outlet/date/name so you can find the exact `special_hours[].id`; do not guess IDs. This deletes the scheduled override only. For today's live open/closed/busy state use `toggle_outlet_status`; for recurring weekly hours use `set_outlet_operating_hours`.

Generate one AI-suggested cross-sell pairing from the menu. Returns the pairing for review — does NOT create anything. Pass the suggested triggering/promoted product IDs to `create_cross_sell_group` once a candidate has been approved. Use this when you want an idea; if you already know the pairing, call `create_cross_sell_group` directly.

Search Atlas help documentation (help.atlas.kitchen) and return matching help pages. Use this when the merchant asks how to use Atlas, the POS, merchant portal, reports, integrations, or APIs. Return the matching documentation pages and cite returned URLs in your answer. Not for the merchant's own live data, records, configuration, sales, or orders. Use `query_data`, `get_sales_report`, or the relevant `get_*` / `list_*` tool for merchant-specific data instead. This calls an external documentation search provider. If the provider is unavailable, return the error to the user instead of retrying blindly.

Get full details for one cash voucher by ID, including redemption count. Use this when the user asks to view, show, inspect, or get details for an explicit cash voucher ID. Use `list_cash_vouchers` to find the ID only when the user did not provide one. To create a voucher, use `create_cash_voucher`. For percentage or amount-off promotions, use discount tools instead.

Get full details for one cross-sell group by id (label, triggering and promoted products, active state). Use `list_cross_sell_groups` to find the id. To change it, use `update_cross_sell_group` or `toggle_cross_sell_group`.

Get one customer's full profile by customer ID, including recent order history, combined total spend, tags, marketing consent, and last activity. If the user already provided a customer ID, call this directly. Use `list_customers` first only when the customer ID is unknown and you need to search or filter for the right customer.

Get a single customer's loyalty balance for a specific brand point program: available points, estimated value, expiring points, and earliest expiry date. Use this before manual rewards adjustments. If you do not know the brand_id or point_program_id, use `list_reward_programs`. Not for the broader customer profile — use `get_customer`.

Get the delivery status of one order by its display identifier (e.g. "QR12"); for all in-flight deliveries across the merchant use `list_active_deliveries`. Returns the trip(s) attached to that order — driver, location, pickup, tracking link, booking attribution — sorted newest-first when rebooks exist. Early-state trips (status `unassigned` or `assigning`) commonly have null driver / driver_location / tracking_link / pickup_at; `pickup` (outlet) and `order` (identifier + prepare_by + delivery_window) are populated as soon as the order exists. To book or cancel a delivery, use `book_delivery` / `cancel_delivery`.

Get configuration details for one discount by ID: schedule, status, limits, conditions, and unreleased claim count. This does not return live redemption history; use `query_data` for redemption counts and trends. Use this when the user asks to view, show, inspect, or get details for an explicit discount ID. Use `list_discounts` to find the ID only when the user did not provide one. To change value, dates, code, or other details, use `update_discount`; to pause or resume it, use `toggle_discount`. If the user asks to change, pause, or resume a specific discount ID, do not call this first; call the write tool directly.

Get one menu with its full structure: sections, sub-sections, products, and modifier groups. Heavy response - prefer `list_menus` to browse, `list_menu_sections` for a lighter section view, or `list_products` to filter products without the full tree. Read-only; to change items use `create_product` / `update_product`.

Get full details of one modifier group: nested modifiers (with price overrides and upsell labels) and the products linked to it. Use `list_modifier_groups` to find the id only when the merchant did not provide one. Group-level settings (name, selection rules, thumbnails, printing) are edited with `update_modifier_group`; modifiers and product links are edited inline via `create_product` / `update_product`.

Look up one operational order record by an exact order reference: line items, payment totals (paid/unpaid), discounts, cash voucher usage, fulfilment, and status. Use `order_id` only for the internal numeric database ID. Use `order_identifier` for any exact order reference the merchant/customer can see: Atlas order numbers from the portal, receipts, delivery tracking, and order lists (e.g. "O102", "P102", "K102", "W102", "QR102", "AG102"), or external platform order codes from channels like GrabFood or Foodpanda. If there is exactly one matching order, this returns full details. If the reference is ambiguous, this returns matching candidates so the merchant can choose. Use this for follow-up questions about whether a specific order used a discount, promo code, platform discount, admin discount, or cash voucher. For payment-level detail (individual captures, methods) or refunds, see `list_order_payments` and `issue_refund`. Not for aggregate sales, revenue, or trends — use `get_sales_report` or `query_data`.

Count operational order records for an outlet matching filters (state, fulfilment type, source, date range). Use this when you only need the number of orders placed, created, received, or ordered during a period; don't `list_orders` just to count. Date filters are by order-CREATION time, not serving date. Do not use this for operational date-range questions about orders the merchant has, needs to serve, fulfil, fulfilled, or has scheduled. Use `get_sales_report` for order counts by serving date.

Get full details for one outlet by id: brands, channels and their diner-facing URLs, regular operating hours, and special hours. Use this for customer-facing URL or QR link requests, including storefront, scan-to-order, and kiosk links. Return the exact channels[].url value from this tool; never construct one from brand, outlet, identifier, or domain pieces. Match the merchant's requested channel to channels[].channel: scan-to-order requests use scan_to_order, kiosk requests use kiosk, and online/web storefront requests use web. Do not answer a scan-to-order request with a web URL. Mention channel status only when the merchant asks about availability, opening, closing, or busy mode, or when the channel entry includes a problem flag such as closed_today or enabled: false. If the user gives an explicit outlet ID, call this tool directly with that ID; do not call `list_outlets` first just to verify it. To change an outlet, use `update_outlet`, `set_outlet_operating_hours`, `toggle_outlet_status`, `set_outlet_special_hours`, or `delete_outlet_special_hours`.

Get full details of one menu item (product or component) by id: description, price, configured unit cost (`cost_cents`, null when not configured), tags, reporting category, linked modifier groups (with overrides), and advance-notice lead times (`lead_times`). Use `list_products` to find the id first only when the user did not provide one. To change the item, use `update_product`; for sold-out, "86", or out-of-stock state, use `update_product_stock`; for scheduled availability windows, use `get_product_availability` / `set_product_availability`. If the user asks to update a specific product ID, do not call this first.

Get a product's scheduled availability rules: when it appears on menus and can be ordered (days of week, time windows, fulfilment types, outlets, date ranges). An empty `availability_rules` list means the product is always available. Always call this before `set_product_availability` when changing an existing setup - that tool replaces all rules, so you need the current ones to preserve what the merchant is not changing. This is scheduling, not stock: for sold-out / "86" state use `get_stock_levels`, and for lead times see `lead_times` on `get_product`.

Check the status of an Atlas Analytics query and retrieve results. Only used to poll a job started by `query_data` — not a standalone query. Poll only when a previous `query_data` call exposed a job_id through tool progress or an explicit timeout/retry path; otherwise call `query_data` again with a narrower prompt. Show the user the progress message each time you poll so they can see what's happening. Terminal states: COMPLETE (message field holds the full answer), or FAILED / CANCELLED (which carry an error instead of a result — stop polling and surface it). Note: Analytics data is refreshed hourly and is not live.

Sales totals (gross/net sales, order counts) for a date range, broken down by one of: outlet, channel, fulfilment type, day, or hour. The fast, synchronous path for "how much did we sell" questions in that shape. E.g. "net sales by outlet in March", "orders per day last week", "revenue by channel yesterday". Use it only when the question maps to one of those breakdowns. For anything else — product- or customer-level breakdowns, rankings beyond the sort fields, custom metrics, or vague / multi-step questions — use `query_data`. Don't rebuild sales from `list_orders`. Dates are by SERVING (fulfilment) date, not order-creation date (`list_orders` and `get_order_count` use creation). For order counts, use this only when the merchant explicitly asks about orders to serve, fulfil, fulfilled, or scheduled (serving-date basis); for how many orders were placed, created, or received in a period, use `get_order_count`. `channel` = order source (pos, kiosk, scan_to_order, web, grab_food, foodpanda, deliveroo) — a separate axis from `fulfilment` (dine_in/pickup/delivery). Amounts are in major currency units (dollars), whereas write tools take minor units (cents). Columns: gross sales = item subtotal; net sales (excl. tax) = subtotal − discounts − points + surcharge + service charge + delivery fee − inclusive tax. Net therefore INCLUDES fees, so it can exceed gross when fees outweigh discounts/tax — net is not simply gross minus discounts. Outlet scoping: pass `outlet_id` only when the merchant explicitly names an outlet or the live context identifies a selected/current outlet. If the merchant says "my outlet" and no current outlet is available, omit `outlet_id` so the result is broken down by outlet rather than guessing. Note: Analytics data is refreshed hourly and is not live. For today/current-day questions, say the numbers may be incomplete or not synced yet.

Get current stock levels for non-archived items at an outlet on a given date. Returns available_quantity per item = configured stock minus committed orders. Items sitting in open diner carts (online / scan-to-order) are NOT subtracted until the order is placed; in-progress POS tickets marked sent-to-kitchen are also not subtracted via this path. Includes products on active menus for the outlet/date even when no finite stock is configured; those rows have stock_configured=false, available_quantity=null, and status=unlimited. Archived products and components are always excluded, even when their IDs are supplied in item_ids. Pass below_threshold to surface only configured low-stock items; when the merchant asks what is "running low" or "low on stock" without a threshold, use below_threshold=10. When the merchant asks which products/items are "out of stock" or "sold out", use below_threshold=0; do not ask for clarification. Item ids are Product or Component ids from `list_products`; use `include_components: true` when checking stock for a component, modifier choice, or ingredient. If the user asks to check stock/stock levels for a specific outlet and gives an outlet_id (for example "outlet 45"), call this directly with that outlet_id; do not call list_outlets first just to verify it. Read-only: to set, block, unblock, or clear stock use `update_product_stock`.

Inspect POS layouts, pages, tiles, product coverage, missing products, and available tile slots. Use this before adding a product to a POS layout unless the caller already gave exact POS layout, page, and product IDs. This tool is read-only. It can list POS layouts when `pos_layout_id` is omitted, inspect one layout when `pos_layout_id` is present, check whether `product_id` is already on the layout, and compare a menu against the layout when `menu_id` is provided.

Issue a refund against a captured order payment (full or partial; base amount or tip). Money-moving and not idempotent unless you pass `idempotency_key` — confirm with the user first. Find the `order_payment_id` with `list_order_payments`; `order_identifier` (the display id like "O102", from `list_orders`/`get_order`) is required as a guard against refunding the wrong payment. Refunds go back to the original payment method and are not reversible. To cancel the whole order instead of refunding, use `cancel_order`. If the user already provides the order_payment_id, order_identifier, and refund amount, call this tool directly; do not call `list_orders` or `list_order_payments` first just to verify them.

List in-flight deliveries for the current merchant (status `assigning` / `assigned` / `dispatched`. Cancelled, completed, pre-provider-confirmation, and aggregator-handled (Foodpanda / GrabFood) deliveries are excluded — aggregator trips have stamped-at-creation status and no live updates, so any answer would be stale. Use `list_orders` filtered by channel to surface aggregator orders). For one specific order, use `get_delivery_status` instead. Response shape: `{ deliveries: [{ trips: [<trip>, ...] }, ...], total_count, page, per_page }`. Each trip carries the same fields as `get_delivery_status` — driver, driver_location, pickup, dropoff, order (identifier + delivery_window), tracking link, booking attribution — sorted newest-booked first. Default `per_page` is 5 to keep latency tolerable (each entry triggers a per-provider HTTP call); pass higher explicitly if needed. NOTE: pagination is at the trip level — in the rare rebook case where one order has multiple active trips, those trips may straddle pages. Pass `outlet_id` to scope to one outlet, `from_date` / `to_date` (YYYY-MM-DD, merchant timezone) to narrow by `orders.serving_date`. To narrow by status, filter `response.deliveries[].trips[]` in the agent — status is computed at read time.

List or search the merchant's cash vouchers. Use this for requests like "find cash voucher ZJ6WCZ", "show active cash vouchers", or "what cash vouchers do I have?". Search by code or label and filter by status (active, expired, redeemed). Start here to find a cash voucher ID only when the user did not provide one, then `get_cash_voucher` for detail. To create one, use `create_cash_voucher`. For percentage or amount-off promotions, use discount tools instead.

List the merchant's cross-sell groups (id, label, active state). Pass `active_only` to skip inactive ones. Start here to find a group id, then `get_cross_sell_group` for detail. To create one, use `create_cross_sell_group` (or `generate_cross_sell` for AI suggestions).

List customers for the current merchant. Search by name, email, or mobile number; filter by spend, order count, age, tags, guest/registered status, marketing consent, signup date, or last-order date; sort by total spend, order count, last order, or signup date. Use this to find customer IDs or build a customer segment. If the user already provided a customer ID, call `get_customer` or `tag_customer` directly instead of listing first. Not for spend analytics or rankings (top spenders, cohort trends, revenue by segment) — use `query_data`.

List the merchant's discounts. Filter by status (active, scheduled, expired, archived), include archived, or search by discount code/name. Start here to find a discount ID only when the user did not provide one, then `get_discount` for full detail. To create one, use `create_discount`. Search respects the status/include_archived filters. If the user asks about a specific code without saying it must be active, search with include_archived=true so archived matches are not missed. Do not use this before updating or toggling a discount when the user already gave a discount ID. For requests like "change discount 22" or "pause discount 22", call `update_discount` or `toggle_discount` directly.

List a menu's top-level sections. Pass `include_products: true` to embed products and sub-sections under each section. Lighter than `get_menu` when you don't need the modifier-group tree. To filter items across a menu use `list_products`; for the full nested structure use `get_menu`. Read-only: this does not move, add, or remove existing products from sections.

List the merchant's menus. Returns metadata only - name, brand, dates, state, tags. Use this to find a menu_id when the merchant names a menu but did not give an ID. Do not call this when an explicit menu_id was provided. Use `get_menu` only when you need the full section/product/modifier tree; use `list_menu_sections` for a lighter section view.

List modifier groups with their options, prices, and selection rules (min/max). Filter by `search` when the merchant provides a modifier group name or identifier, pass `linked_to_product_id` to scope to one product's groups, or `get_modifier_group` for one group's full detail. If search returns multiple groups with the same name, use the returned ids, identifiers, and context to pick the intended group before calling `get_modifier_group`. To find a group when its ID is unknown, keep the default page size because every result includes nested modifier and item details. If no match is in the current page and `page * per_page < total_count`, request the next page with the same page size. Do not report a group as missing from the current scope until every page is inspected. Read-only here: there is no standalone tool to edit a modifier group - create or change them inline through `create_product` / `update_product` (or in the dashboard).

List order payments, filtered by date range, outlet, payment method, and amount, to find specific payments. Use the returned `id` as `order_payment_id` when calling `issue_refund`. This is the correct tool for payment queries such as "payments over $20", payment methods, captured/uncaptured payment records, or finding a payment ID; do not call `list_orders` first for payment amount filtering. Not for revenue or payment-mix reporting — use `get_sales_report` (sales totals) or `query_data` (anything analytical).

List orders for an outlet (filter by state, fulfilment type, source, or date range) to find or inspect specific operational order records. Returns order summaries (incl. the display `identifier` like "O102", needed by `issue_refund`). Use `search` for broad or partial lookup by Atlas identifier, external platform order code, or customer contact details. If the user gives one exact order reference, use `get_order`. Date filters are by order-CREATION time, not serving date (`get_sales_report` uses serving date). Use `get_order` for one order's full detail (line items, payments), or `get_order_count` when you only need the number. Not for sales reporting or trends — use `get_sales_report` (totals) or `query_data` (anything analytical); don't sum orders yourself. If the user asks to show/list recent orders for a specific outlet and gives an outlet ID (for example "outlet 45"), call this tool directly with that outlet_id; do not call `list_outlets` first just to verify it.