qwen_agent/skills/developing/ecommerce-storefront/hooks/ecommerce_guide.md

E-Commerce Storefront Tools Usage Guide

Two tools are available for e-commerce product browsing and ordering:

• render_product_list — Display interactive product cards with spec selection
• render_order_confirm — Display order confirmation with payment options

---

1. render_product_list

When to use: User wants to browse, search, or buy products. Show product cards with images, prices, and selectable specs (size, flavor, color, etc.).

The user can select specs and click "Add to Cart" on any product. The selection is returned as an mcp-app-response containing: { product_id, product_name, selected_specs: {...}, final_price, quantity }.

render_product_list(
  title="Coffee Menu",
  products=[
    {
      "id": "latte-001",
      "name": "Caffe Latte",
      "description": "Rich espresso with steamed milk",
      "image": "https://images.unsplash.com/photo-1572442388796-11668a67e53d?w=300&h=200&fit=crop",
      "price": 4.50,
      "currency": "$",
      "specs": [
        {
          "label": "Size",
          "options": [
            {"name": "Small", "price_delta": 0},
            {"name": "Medium", "price_delta": 0.5},
            {"name": "Large", "price_delta": 1.0}
          ]
        },
        {
          "label": "Milk",
          "options": [
            {"name": "Whole Milk", "price_delta": 0},
            {"name": "Oat Milk", "price_delta": 0.6},
            {"name": "Almond Milk", "price_delta": 0.6}
          ]
        }
      ],
      "tags": ["Hot", "Popular"]
    }
  ]
)

After receiving the user's selection, proceed to generate an order and call render_order_confirm.

---

2. render_order_confirm

When to use: After the user selects a product and you have generated an order.

Payment method options:

• "button" — Simple confirm/cancel buttons (default)
• "qrcode" — Show a QR code image for mobile payment
• "link" — Provide an external payment URL

render_order_confirm(
  title="Order Confirmation",
  order={
    "order_id": "ORD-20260522-001",
    "items": [
      {"name": "Caffe Latte (Large, Oat Milk)", "quantity": 1, "price": 6.10}
    ],
    "subtotal": 6.10,
    "tax": 0.49,
    "total": 6.59,
    "currency": "$"
  },
  payment={
    "method": "button",
    "button_text": "Confirm Payment"
  }
)

The user response will be: { action: "confirm", order_id } or { action: "cancel", order_id }.

---

Workflow

The typical e-commerce flow is:

1. User asks to buy something → call render_product_list
2. User selects a product → receive mcp-app-response with selection details
3. Generate order from selection → call render_order_confirm
4. User confirms or cancels → receive mcp-app-response with action
5. If confirmed → process payment / show success message
6. If cancelled → ask user what they'd like to do next

Tips

• Always include product images when available for better visual experience
• Use tags like "Hot", "New", "Sale" to highlight special products
• Keep product descriptions short (under 50 characters)
• Generate a unique order_id for each order
• Include tax/discount breakdowns when applicable for transparency