lua-shopify

🛒 Lua Shopify Agent

A conversational AI agent for Shopify stores built with Lua CLI. Enables natural language product search, cart management, and checkout.

Features

• Product Search - Vector search across your Shopify catalog
• SKU Lookup - Find products by exact SKU
• Stock Checking - Real-time inventory levels from Shopify
• Cart Management - Add, remove, clear items
• Checkout - Generate Shopify payment links
• Auto-Sync - Products sync every 30 minutes via scheduled job
• Stale Product Cleanup - Automatically removes products deleted from Shopify
• Webhooks - Real-time product create/update/delete from Shopify

Quick Start

# 1. Install dependencies
npm install

# 2. Set environment variables
lua env sandbox -k SHOPIFY_DOMAIN -v "your-store.myshopify.com"
lua env sandbox -k SHOPIFY_ACCESS_TOKEN -v "shpat_xxx"
lua env sandbox -k SHOPIFY_CURRENCY -v "USD"

# 3. Sync products from Shopify
lua test job --name sync-shopify-products

# 4. Test tools
lua test skill --name search --input '{"query": "leather bag"}'

# 5. Chat with your agent
lua chat

# 6. Deploy to production
lua push all --force --auto-deploy

Project Structure

lua-shopify/
├── src/
│   ├── index.ts                 # LuaAgent configuration
│   ├── api/
│   │   └── shopify.api.ts       # Shopify REST/GraphQL API
│   ├── dtos/
│   │   ├── basket.dto.ts        # Basket types
│   │   └── product.dto.ts       # Product types
│   ├── services/
│   │   ├── config.ts            # Environment helpers
│   │   ├── shopify-service.ts   # Business logic
│   │   └── worker-service.ts    # Product sync service
│   ├── skills/
│   │   ├── shopify-skill.ts     # Skill with context prompt
│   │   └── tools/
│   │       └── shopify-tools.ts # 11 tools
│   ├── jobs/
│   │   └── sync-products.job.ts # Scheduled product sync
│   └── webhooks/
│       └── product-update.webhook.ts
├── lua.skill.yaml               # Agent manifest
├── package.json
└── env.example

Tools

Tool	Description
search	Vector search for products
getProductById	Get full product details
findProductBySku	Find product by exact SKU
checkVariantStock	Check real-time inventory
addToBasket	Add item to cart (with stock check)
getBasket	Get current cart
removeFromBasket	Remove item from cart
clearBasket	Clear entire cart
checkout	Generate Shopify checkout link
getAllUsersBaskets	Admin: view all baskets
sendProductDetails	Push product cards to user

Environment Variables

Variable	Description	Required
SHOPIFY_DOMAIN	Your myshopify.com domain	✅
SHOPIFY_ACCESS_TOKEN	Shopify Admin API access token	✅
SHOPIFY_CURRENCY	Currency code (default: USD)	❌

Getting Your Shopify Credentials

1. Go to Shopify Admin → Settings → Apps and sales channels
2. Click Develop apps → Create an app
3. Configure Admin API scopes:
   • read_products
   • write_products
   • read_inventory
   • write_draft_orders
4. Install the app and copy the Admin API access token

Webhook Setup

After deploying, configure webhooks in Shopify to receive real-time product updates:

1. Go to Shopify Admin → Settings → Notifications → Webhooks
2. Create webhooks for:

Topic	Webhook URL
Product creation	https://webhook.heylua.ai/{agentId}/shopify-product-update
Product update	https://webhook.heylua.ai/{agentId}/shopify-product-update
Product deletion	https://webhook.heylua.ai/{agentId}/shopify-product-delete

3. Set format to JSON

Replace {agentId} with your agent ID from lua.skill.yaml

Commands

Command	Purpose
lua test job --name sync-shopify-products	Sync all products
lua test skill --name search --input '{...}'	Test a tool
lua chat	Interactive chat
lua push all --force	Deploy everything
lua logs	View execution logs

Example Conversation

User: I'm looking for a leather bag
Agent: Here are 5 leather bags I found...
       [horizontal-list-item cards]

User: Tell me more about the Bolso Bag
Agent: [images gallery]
       # Bolso Bag - Taupe
       ## 2695.00 ZAR
       [actions: Add to Cart, Buy Now]

User: Add it to my cart
Agent: I've added the Bolso Bag - Taupe to your cart!

User: Checkout please
Agent: ::: payment
       [Complete checkout here](https://checkout.yourstore.com/...)
       :::

Documentation

• Lua CLI Docs
• Products API
• Baskets API
• Webhooks
• Jobs

---

Built with Lua CLI