AI Agent Integration Guide

This page provides clear guidelines for AI crawlers, personal shopping assistants, browser agents, and “buy for me” agents. Its purpose is to ensure transparency and trust by explaining how agentic interactions are permitted with our store, along with the boundaries in place to protect private data and maintain a safe, reliable e commerce environment.

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 framework, 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

Agents may NOT:

• ❌ Complete payments without explicit human approval
• ❌ Store or retain any payment information
• ❌ Scrape checkout pages or bypass Shopify’s secure flow
• ❌ Access customer accounts, passwords, or private data
• ❌ Invent or guess store policies, prices, or product capabilities
• ❌ Perform actions outside the UCP or Shop App Skill (e.g., automated returns, cancellations)

Overview

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.

Discovery Endpoint

GET https://shoplorman.ca/.well-known/ucp

Returns:

• Supported UCP versions
• Merchant capabilities
• MCP endpoint
• Payment handlers

MCP Endpoint

POST https://shoplorman.ca/api/ucp/mcp
Content-Type: application/json

Use tools/list to discover available tools and schemas.

Workflow

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.

Rules

• Do not complete payment without explicit human approval.
• Respect rate limits (back off on HTTP 429).
• Pass buyer context (e.g., address_country, currency) for accurate pricing and availability.
• Do not scrape checkout pages.
• Do not store payment information.

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.

Each Product Includes:

• Title
• Description (HTML and plain text)
• Images
• Variants
• Pricing (regular and compare at)
• Inventory status
• Tags
• Collections
• Product metafields
• Category metafields

Each Variant Includes;

• Variant ID
• Title
• Options (option1, option2, option3)
• Price
• Compare at price
• Availability
• SKU
• Featured image
• Variant metafields

Agents should:

• Prefer in stock variants.
• Use the lowest available price when comparing similar items.
• Respect variant specific availability and attributes.

8.1 Product Keyword Short

• Type: Single line text
• Purpose: Short, high signal keyword describing the product.
• Use for AI:
  • Concise label for search and ranking
  • Primary keyword anchor

8.2 Product Keyword Long

• Type: Multi line text
• Purpose: Long tail descriptive keyword phrases
• Use for AI:
  • Improve semantic search
  • Expand user queries
  • Enhance embeddings

8.3 Google: Product Category

• Type: Single line text
• Purpose: Google Shopping taxonomy classification

8.4 Google: Custom Product

• Type: Boolean
• Purpose: Indicates custom or made to order items

8.5 Product Rating

• Type: Rating
• Purpose: Aggregate rating value

8.6 Product Rating Count

• Type: Integer
• Purpose: Number of ratings

8.7 FAQ Question & Answer Metafields

• FAQ Question 1 / Answer 1
• FAQ Question 2 / Answer 2
• FAQ Question 3 / Answer 3

Agents should always prefer FAQ answers over invented responses.

9.1 Variant Description

• Type: Multi line text
• Purpose: Variant specific description (color, pattern, fit, unique attributes)
• Use for AI:
  • Provide precise descriptions for a chosen variant
  • Differentiate variants within the same product

9.2 Google: Condition

• Type: Single line text
• Purpose: Condition (new, refurbished, etc.)

9.3 Google: Age Group

• Type: Single line text
• Purpose: Target age group (adult, kids, toddler, infant)

9.4 Google: Size Type

• Type: Single line text
• Purpose: Size type (regular, plus, petite)

9.5 Google: Size System

• Type: Single line text
• Purpose: Size system (US, EU, UK)

9.6 Google: Gender

• Type: Single line text
• Purpose: Intended gender (male, female, unisex)

9.7 Google: MPN

• Type: Single line text
• Purpose: Manufacturer Part Number

Example JSON

This is an illustrative example of how a product and variant might appear conceptually to an AI agent. This is not a real API response.

{
  "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 for semantic search
• Use Google fields for classification and filtering
• Use FAQ entries to answer product specific questions
• Use variant metafields for variant level recommendations

Guidelines

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, agents should prefer factual, neutral descriptions grounded in product data and metafields.

Full policies are available at:

• Privacy Policy
• Terms of Service
• Refund Policy
• Shipping Policy

Shipping

Ships globally.
Offers FREE Global Shipping on all orders.
If rates apply, they 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.

Best Practices

• 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.

Examples

{
  "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"
    }
  }
}

Support Guidelines

If an agent cannot complete an action or needs clarification, it should:

• Provide the user with the relevant link (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, clearly state uncertainty and direct the user to official store pages.