Room Service FAQ
For owners
Can I edit a published item without breaking existing orders?
Yes. Editing the name, description, price, or category updates the
menu row and the backing WC product in lockstep. Past orders keep
the original line-item description and unit price (they're snapshotted
into wp_folio_items at order time).
What if a guest orders something we're out of?
Open the Menu Manager, find the item, click Edit, uncheck "Available", and save. The item becomes hidden in chat and the SPA immediately. Toggle it back on later instead of deleting — guest chat history with the item name stays useful.
How do I see today's room service orders?
Open wp-admin → Kitchen — see the Kitchen workflow doc for the full board. Today's orders are pre-filtered automatically. For a deeper revenue/analytics view, the Operations dashboard panel is still on the v1.3 roadmap; in the meantime the Kitchen board is the source of truth.
Can the AI extraction handle a wine list with two prices per item?
Yes. The model is instructed to split items with multiple prices (e.g. "Mojito — glass $6 / pitcher $20") into two rows distinguished by name suffix. Confidence drops a bit for these — review before publishing.
Where does the kitchen notification go?
The order endpoint fires a do_action('hilucy_menu_order_kitchen_notify', $payload)
hook. Existing Matrix and WhatsApp staff bridges can listen and route
the message — see Matrix integration
for the standard staff routing. v1.1 also writes the notification
payload to debug.log as a fallback.
How do I disable AI extraction for a specific environment?
Don't set OPENAI_API_KEY (constant or option) on that environment.
The dashboard shows a yellow "AI extraction disabled" banner and
falls back to the manual add path. The 501-style error returned by
POST /hilucy/v1/menu/extract includes a clear "set OPENAI_API_KEY"
message so future debugging is obvious.
For guests (and staff fielding guest questions)
Can a guest order on someone else's room?
No. Orders are tied to the authenticated guest's session. The folio
charged is the open folio for (user_id, listing_id). If a companion
wants to charge a primary's room, the primary needs to place the
order or staff needs to add the item via the Folio dashboard.
What if no folio is open when the guest orders?
The order endpoint creates a pending WooCommerce order and returns a Stripe checkout URL. Lucy renders this as a "Pay & confirm" button in the chat; the SPA shows it inline in the success banner. The kitchen is notified only after payment in this path.
How does the price show up if my menu is in pesos?
Prices are stored in USD cents (the canonical currency for HiLucy
billing). If you uploaded a menu in MXN, the AI extractor converts at
17.5 MXN ≈ 1 USD by default. You can override the rate via the
hilucy_mxn_usd_rate filter — useful for properties that prefer to
peg to a different rate.
Can I refund a room service item?
Today: through Stripe (per-charge fallback path) or by voiding the folio item before the folio closes. UI for refunds in the Operations dashboard is in the v1.2 plan.
Why doesn't the room-service card appear on the dashboard?
The dashboard tile + chat starter prompts only render when the SPA
knows which property the guest is at (the hilucy_listing_id
cookie). The cookie is set automatically when the guest:
- Completes the arrival flow at
/arrive/[token] - Visits any room-service page with
?listing_id=… - Has it set explicitly (admin debug)
If a guest is missing the cookie, send them a fresh arrival link or
a deep link with ?listing_id= so the cookie gets written.
Edge cases
A 35-item menu took 3 minutes to publish
Normal. Each backing WC product save is heavy because of the chain of WooCommerce hooks (term taxonomy refresh, search index, vendor sync). The dashboard chunks publishes into batches of 3 to stay under Cloudflare's 100-second edge timeout — you'll see the Menu items count tick up as each chunk lands.
"signal is aborted without reason" during publish
A specific chunk request exceeded the 75-second client timeout. Already-published items are kept. Reload the page, look at the items list to see what landed, and re-extract → publish only the missing items.
A guest's name doesn't carry through from chat to the kitchen notification
Lucy pulls guest_name and guest_phone from graph state if not
explicitly given by the LLM call. If state has neither, the tool
returns a "please ask the guest" message. Most often this happens for
guests who started chatting before going through the arrival flow
(their session has no name yet). The arrival flow populates state.