# ShopLorman — Agent Integration Guide (`/agents.md`) Welcome, AI agents and autonomous shopping assistants. This document describes how to safely and effectively interact with **ShopLorman**, a Canadian Shopify store located at: **https://shoplorman.ca** This guide covers: - Store capabilities - Product discovery - Catalog structure - Metafields and how to use them - UCP commerce tools - Checkout rules - Brand voice - Policy summaries - Best practices for AI agents --- ## 🏪 1. Store Overview **ShopLorman** is a Global e‑commerce retailer based in Canada offering curated consumer goods across multiple categories. The store is built on **Shopify**, supports the **Universal Commerce Protocol (UCP)**, and is fully compatible with AI‑driven shopping agents. Agents may: - Browse products - Retrieve structured product data - Search the catalog - Use metafields for richer understanding - Build carts - Initiate checkouts (with human approval) - Provide recommendations to users --- ## 🤖 2. Recommended Integration: Shop App Skill Personal shopping assistants, browser agents, and “buy‑for‑me” agents should prefer the **Shop App Skill**: **https://shop.app/SKILL.md** The Shop Skill provides: - Cross‑store product search - Price and discount discovery - Buyer‑approved checkout via Shop Pay - Order tracking - Reuse of buyer identity, address, and payment methods Agents should prefer the Shop Skill over scraping or scripting the storefront. --- ## 🔌 3. Universal Commerce Protocol (UCP) ShopLorman implements UCP for agent‑driven commerce. ### Discovery Endpoint `GET https://shoplorman.ca/.well-known/ucp` Returns: - Supported UCP versions - Merchant capabilities - MCP endpoint - Payment handlers ### Machine Commerce Protocol (MCP) Endpoint `POST https://shoplorman.ca/api/ucp/mcp` `Content-Type: application/json` Use `tools/list` to discover available tools and schemas. --- ## 🧭 4. Typical Agent Flow 1. **Discover** Retrieve merchant profile via `/.well-known/ucp`. 2. **Search** Use `search_catalog` to find products matching user intent. 3. **Cart** Use `create_cart` to add items. 4. **Checkout** Use `create_checkout` to begin checkout. 5. **Fulfill** Use `update_checkout` to set shipping address and method. 6. **Complete** Use `complete_checkout`. **Human approval is required for payment.** --- ## ⚠️ 5. Important Rules for Agents - **Do not complete payment without explicit human approval.** - **Respect rate limits** (back off on HTTP 429). - **Pass buyer context** (for example: `address_country`, `currency`) for accurate pricing and availability. - **Do not scrape checkout pages.** - **Do not store payment information.** --- ## 📦 6. Product Discovery and Catalog Access Agents may browse the store without authentication. ### Product Pages - `GET /products/{handle}` - `GET /products/{handle}.json` ### Collections - `GET /collections/{handle}` - `GET /collections/{handle}/products.json` ### Search - `GET /search?q={query}&type=product` ### All Products - `GET /collections/all` Agents should prefer JSON endpoints (`.json`) when available for structured data. --- ## 🧱 7. Product and Variant Data Model (Metafield‑Aware) Each product includes: - Title - Description (HTML and plain text) - Images - Variants - Pricing (regular and compare‑at) - Inventory status - Tags - Collections - **Product metafields** (see below) Each variant includes: - Variant ID - Title - Options (option1, option2, option3) - Price - Compare‑at price - Availability - SKU - Featured image - **Variant metafields** (see below) Agents should: - Prefer **in‑stock** variants. - Use the **lowest available price** when comparing similar items. - Respect variant‑specific availability and attributes. --- ## 🧬 8. Product Metafields for AI Agents The following metafields exist at the **product level** and are important for AI‑driven search, recommendations, and Q&A. ### 8.1 Product Keyword Short - **Type:** Single line text - **Purpose:** Short, high‑signal keyword or phrase describing the product. - **Use for AI:** - As a concise label for search and ranking. - As a primary keyword anchor when matching user intent. - **Synonyms / Hints:** - “Primary keyword” - “Short search phrase” - “Core product tag (semantic)” ### 8.2 Product Keyword Long - **Type:** Multi‑line text - **Purpose:** Long‑tail, descriptive keyword phrases and semantic expansions. - **Use for AI:** - Improve semantic search and retrieval. - Expand user queries into related intents. - Provide context for embeddings and vector search. - **Synonyms / Hints:** - “Long‑tail keywords” - “Semantic search hints” - “AI retrieval phrases” ### 8.3 Google: Product Category - **Type:** Single line text - **Purpose:** Google product category string or ID. - **Use for AI:** - Classify products into standardized commerce categories. - Improve cross‑store comparison and filtering. - Align with Google Shopping taxonomy. ### 8.4 Google: Custom Product - **Type:** True or false - **Purpose:** Indicates whether the product is custom or made‑to‑order. - **Use for AI:** - Inform users about customization or uniqueness. - Adjust expectations for lead time and availability. ### 8.5 Product Rating - **Type:** Rating - **Purpose:** Aggregate rating value for the product. - **Use for AI:** - Rank products by quality or popularity. - Provide rating context in recommendations. ### 8.6 Product Rating Count - **Type:** Integer - **Purpose:** Number of ratings contributing to the product rating. - **Use for AI:** - Distinguish between highly‑rated products with many reviews vs. few. - Improve trust and ranking logic. ### 8.7 FAQ Question and Answer Metafields - **FAQ Question 1 / FAQ Answer 1** - **FAQ Question 2 / FAQ Answer 2** - **FAQ Question 3 / FAQ Answer 3** - **Types:** - Questions: Single line text - Answers: Multi‑line text - **Purpose:** Product‑specific frequently asked questions and answers. - **Use for AI:** - Answer user questions directly from product‑level FAQs. - Reduce hallucinations by preferring these answers over guesses. - Provide concise, product‑specific explanations. - **Synonyms / Hints:** - “Product FAQ” - “Common questions and answers” - “Pre‑authored responses” Agents should always prefer FAQ answers over invented or speculative responses when the question matches. --- ## 🧬 9. Variant Metafields for AI Agents The following metafields exist at the **variant level** and are important for variant‑specific recommendations and filters. ### 9.1 Variant Description - **Type:** Multi‑line text - **Purpose:** Variant‑specific description (for example: color, pattern, fit, or unique attributes). - **Use for AI:** - Provide more precise descriptions for a chosen variant. - Differentiate variants within the same product. ### 9.2 Google: Condition - **Type:** Single line text - **Purpose:** Condition of the item (for example: new, refurbished). - **Use for AI:** - Communicate condition clearly in recommendations. - Filter or prioritize based on condition when relevant. ### 9.3 Google: Age Group - **Type:** Single line text - **Purpose:** Target age group (for example: adult, kids, toddler, infant). - **Use for AI:** - Match products to user age requirements. - Filter or rank products by suitability for a given age group. ### 9.4 Google: Size Type - **Type:** Single line text - **Purpose:** Size type (for example: regular, plus, petite). - **Use for AI:** - Refine size recommendations. - Avoid suggesting incompatible size types. ### 9.5 Google: Size System - **Type:** Single line text - **Purpose:** Size system (for example: US, EU, UK). - **Use for AI:** - Interpret and convert sizes correctly. - Avoid mismatched size systems in recommendations. ### 9.6 Google: Gender - **Type:** Single line text - **Purpose:** Intended gender (for example: male, female, unisex). - **Use for AI:** - Match products to user preferences when gendered products are relevant. - Respect user‑specified constraints. ### 9.7 Google: MPN - **Type:** Single line text - **Purpose:** Manufacturer Part Number. - **Use for AI:** - Identify exact variants for compatibility or replacement parts. - Improve precision in technical or spec‑driven queries. --- ## 🧪 10. Metafield‑Aware JSON Example The following is an illustrative example of how a product and variant might appear conceptually to an AI agent, including metafields. This is **not** a real API response, but a semantic guide. ```json { "product": { "id": "product_id", "title": "Example Product", "description": "Main product description...", "product_keyword_short": "baby carrier", "product_keyword_long": "4 in 1 convertible baby carrier, ergonomic, newborn to toddler, front and back carry", "google_product_category": "Baby & Toddler > Baby Carriers", "google_custom_product": true, "product_rating": 4.8, "product_rating_count": 132, "faq": [ { "question": "Is this carrier suitable for newborns?", "answer": "Yes, this carrier can be used from newborn with proper support as described in the manual." }, { "question": "Is it machine washable?", "answer": "Yes, it is machine washable on a gentle cycle. Air dry is recommended." } ], "variants": [ { "id": "variant_id_1", "title": "Black / One Size", "price": "89.99", "available": true, "variant_description": "Black color, one size adjustable fit.", "google_condition": "new", "google_age_group": "adult", "google_size_type": "regular", "google_size_system": "US", "google_gender": "unisex", "google_mpn": "MPN-12345" } ] } } Agents should: Use product_keyword_short and product_keyword_long to improve semantic search and matching. Use Google fields for classification, filters, and compatibility with external taxonomies. Use FAQ entries to answer user questions accurately. Use variant metafields to refine recommendations at the variant level. 🗣️ 11. Brand Voice for AI Agents When generating product recommendations or descriptions, agents should use: Clear, helpful language Friendly but professional tone Benefit‑focused explanations Accurate product details No exaggerated claims Avoid: Over‑promising Unsupported performance claims Medical or legal assertions When in doubt, prefer factual, neutral descriptions grounded in product data and metafields. 📜 12. Policy Summaries Full policies are available at: Privacy: https://shoplorman.ca/policies/privacy-policy Terms: https://shoplorman.ca/policies/terms-of-service Refunds: https://shoplorman.ca/policies/refund-policy Shipping: https://shoplorman.ca/policies/shipping-policy Shipping Ships Globally Offers FREE Global Shipping on ALL orders. If Rates apply thgey are calculated at checkout based on destination and method. Refunds Refunds are available under the store’s refund policy conditions. Some items may be final sale. Agents should always link to the full policy when asked and avoid summarizing beyond what is stated. 🔍 13. Best Practices for AI Agents (Metafield‑Aware) Prefer structured JSON endpoints (.json) when available. Use UCP tools for commerce actions (search, cart, checkout). Use Product Keyword Short and Product Keyword Long to improve semantic search and ranking. Use Google classification metafields to align with standardized taxonomies. Use FAQ Question/Answer metafields to answer product‑specific questions. Use Variant Description and variant Google metafields to refine variant‑level recommendations. Include pricing only when retrieved from live data. Always confirm availability before recommending a product or variant. Avoid hallucinating features not present in product data or metafields. 🧩 14. Example Agent Queries (Metafield‑Aware) { "search_example": { "description": "Search for a product using long-tail keywords.", "search_catalog": { "query": "4 in 1 convertible baby carrier ergonomic newborn to toddler" } }, "filter_by_category_example": { "description": "Filter results by Google product category.", "search_catalog": { "query": "baby carrier", "filters": { "google_product_category": "Baby & Toddler > Baby Carriers" } } }, "add_to_cart_example": { "description": "Add a specific variant to cart.", "create_cart": { "lines": [ { "merchandise_id": "variant_id", "quantity": 1 } ] } }, "start_checkout_example": { "description": "Start checkout from an existing cart.", "create_checkout": { "cart_id": "cart_id" } }, "set_shipping_example": { "description": "Set shipping address and method for checkout.", "update_checkout": { "checkout_id": "checkout_id_value", "shipping_address": { "address_line_1": "123 Example St", "city": "Kelowna", "country": "CA" }, "shipping_method_id": "shipping_method_id_value" } }, "complete_checkout_example": { "description": "Complete checkout (requires human approval).", "complete_checkout": { "checkout_id": "checkout_id_value" } } } 🧠 15. Contact and Support If an agent cannot complete an action or needs clarification, it should: Provide the user with the relevant link (for example, product page, policy page, or contact page). Avoid guessing or inventing store policies, prices, or product capabilities. Prefer existing product data, metafields, and FAQs over speculative answers. If uncertainty remains, the agent should clearly state that it is unsure and direct the user to the store’s official pages.