medusa-store
Reference for the Medusa.js store backend, its Next.js storefront, and the Claude-powered AI store agent. Use this whenever working on the store backend/frontends — product catalog, checkout, digital
SKILL.md.claude/skills/medusa-store/SKILL.md
GitHubMedusa Store + AI Agent — Reference
Stack
- Backend: Medusa.js (store/backend), started from
medusajs/medusa-starter-default - Storefront: the official Medusa Next.js storefront template (store/storefront), customized
- Products: both physical and digital (digital products plugin enabled — used to sell the dubbing service itself as a product)
- Database: Dedicated PostgreSQL database (separate from Supabase; manages products, orders, customers, regions, etc.)
AI Store Assistant (customer-facing chat widget)
A floating chat widget on the storefront. On every message:
- Frontend sends
{ message, conversationId }toAI_GATEWAY_URL/ai/chatwithcontext: "store-chat" - The AI Gateway attaches the product catalog + FAQ + store policies (in Arabic) as system context
- Response streams back to the widget
The widget NEVER calls Claude directly — always through the gateway (see ai-gateway skill). The widget also never holds any API key.
AI Store Management Agent (admin-facing, "AI does everything")
This is the agent the store owner talks to in Arabic to run the store. It uses Claude tool-calling. Each tool below is a function that calls the Medusa Admin API. The AI Gateway holds these tool definitions under context: "store-admin".
| Tool | Medusa Admin API call | Notes |
|---|---|---|
create_product |
POST /admin/products |
Takes title, price, description, images. If description is missing, the agent writes one in Arabic itself before calling this. |
list_orders |
GET /admin/orders |
Supports filters: status, date range |
update_inventory |
POST /admin/inventory-items/:id/location-levels/:location_id |
Adjusts stock quantity for a variant |
create_discount |
POST /admin/discounts |
Generates a coupon code, % or fixed amount |
get_sales_report |
GET /admin/orders + aggregation |
Revenue, top products, conversion — computed from order data |
write_description |
(no API call — pure generation) | Generates Arabic product description + SEO title + tags; output is then passed to create_product or update_product |
answer_customer |
reads from /admin/orders, /admin/customers |
Looks up a customer's order by email/order number, drafts a reply |
process_refund |
POST /admin/orders/:id/refund |
Always confirm the amount and order ID with the user before calling — refunds are irreversible |
Adding a new tool
- Define the JSON schema (name, description, input_schema) in the AI Gateway's tool registry for
context: "store-admin" - Implement the handler function that calls the relevant Medusa Admin API endpoint
- Add a row to the table above
- Irreversible actions (refunds, deleting products) must require the agent to restate the action and get explicit confirmation before calling the tool
Security Notes (also see security-engineering skill — especially Section 4 on customer/admin tool separation, critical for the admin agent's tools above)
- The Medusa Admin API key lives ONLY in the AI Gateway's
.env— never in the storefront, never in the chat widget's frontend code - All admin-tool calls happen server-side (AI Gateway → Medusa Admin API), the admin chat UI just sends/receives messages
- Rate limit the storefront chat widget endpoint — without it, anyone can spam it and burn Claude API credits
Selling Dubbing as a Product
The dubbing service itself is listed as a digital product in Medusa. When a customer buys it, the order triggers a webhook to DUBBING_URL/api/dub to create a dubbing job tied to that order ID — this is the one place the Store service calls Dubbing directly (via HTTP, per the architecture rule).