Shopify

• A Shopify store where you can install apps and edit the theme.
• The grants the app requests: read and write products, read inventory, write checkouts, draft orders, and orders, read content, and read and write themes (the theme grants install the widget).

1

Shopify admin: install the app

Open Lua AI Shopping Assistant in the Shopify App Store, select Install, and accept the access request.

Shopify then opens the admin dashboard inside Shopify admin; the agent, its organization, and the first catalog sync are created in this step, and a persona is drafted in the background.

2

Shopify admin: switch on the storefront widget

In Sales channels › Online Store › Themes, select Customize, open App embeds, switch LuaPop Chat on, set position, theme, button text, and colors, then select Save.

The embed’s settings cover position, theme, button text, icon, and color, chat title, window size, link previews, and custom CSS for the button and header; the full option set is on Style the web widget.

3

Storefront: try it

Open the store, open the widget, and ask for a product, for example “Show me black pouches under $50”. The agent searches the synced catalog, sends product cards, and can add a variant to the basket and return a checkout link.

​

What the agent can do

• Search products by description (raising the result limit for products sold as many color variants), find products by SKU, get one product’s details, and send product cards.
• Check whether a variant is in stock.
• Add to, remove from, show, and clear the end user’s basket, and check out: the agent creates a Shopify draft order, returns its checkout URL for the end user, and records the order as pending.

​

How the catalog stays in sync

• A full refresh runs every hour: products whose Shopify status is ACTIVE are searchable, others are marked inactive, and products no longer in Shopify are removed.
• Product create, update, and delete webhooks, registered at install, refresh a single product immediately.
• A store with no conversation for 30 days stops refreshing until the next message arrives; a newly installed store always gets its first sync.
• A 401, 402, 403, or 404 from Shopify pauses the sync for 24 hours; three in a row stop it until support restores it.

import type { LuaTool } from 'lua-cli';
import { Products } from 'lua-cli';
import { z } from 'zod';

export default class FindGiftTool implements LuaTool {
  name = 'find_gift';
  description = 'Suggest products from the synced store catalog for a gift brief';
  inputSchema = z.object({ brief: z.string().describe('Who the gift is for and the budget') });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Products.search(input.brief);
    return result.map((product) => product.data);
  }
}

lua test skill --name find_gift --input '{"brief":"a coffee lover, under $40"}' --ci

​

Raw API access

​

Limits

• One store per agent; install the app on each store that needs an agent.
• No order lookup, and no inventory levels beyond the variant stock check.

​

If it isn’t working

​

Next steps