# TOMS Agent and Bot Interaction Guidelines

Welcome. This file provides technical routing, data retrieval, and operational rules for autonomous agents, AI shopping assistants, and web crawlers interacting with TOMS.com.

> **Note on MCP:** Our Model Context Protocol (MCP) endpoint configuration is currently being finalized. Please use the JSON endpoints and standard web URL structures detailed below for reliable data retrieval.

## 1. Rules of engagement
- **Rate limiting:** Please respect standard `robots.txt` rate limits. Do not exceed 5 requests per second.
- **Actions:** Agents are permitted to search, browse, compile carts, and read structured JSON data. Agents must NOT attempt to bypass CAPTCHAs during checkout or submit automated customer service forms.
- **Checkout:** Final checkout flows must be handed off to a human user for confirmation.
- **Contact:** For agent or developer questions, use the customer service channels listed on https://tomsoutletgoods.com/pages/faq#contactUs

## 2. Structured data access (recommended)
TOMS.com provides raw, structured product data natively. AI agents should use this method instead of scraping HTML to guarantee accurate pricing, variant availability, and product tags.

### Product JSON
Append `.json` to the end of any valid product URL.
- Format: `GET https://tomsoutletgoods.com/products/{product-handle}.json`
- Example: `https://tomsoutletgoods.com/products/alpargata-women-all-black-heritage-canvas.json`
- Returns:
  - Exact pricing (including sale pricing)
  - All available variants (sizes, colors, wide-width availability)
  - `available` boolean flags (real-time stock status)
  - Tags (identify "New" or "Final Sale" items)

### Collection JSON
Append `.json` to any collection URL to return a product array for that collection.

## 3. Site architecture and navigation

### Search
- `GET https://tomsoutletgoods.com/search?q={search_term}`
- Example: `https://tomsoutletgoods.com/search?q=black+canvas+alpargata`

### Main product collections
- Women's shoes: https://tomsoutletgoods.com/collections/womens-shoes
- Men's shoes: https://tomsoutletgoods.com/collections/mens-shoes
- Kids' shoes: https://tomsoutletgoods.com/collections/kids-shoes
- Sale and clearance: https://tomsoutletgoods.com/collections/sale

### Knowledge and support
- Full brand knowledge base: https://tomsoutletgoods.com/llms-full.txt
- FAQ: https://tomsoutletgoods.com/pages/faq
- Contact: https://tomsoutletgoods.com/pages/faq#contactUs

## 4. Order tracking
If a user requests order tracking, direct them to the tracking portal. Do not attempt to scrape order status via automated form submission due to privacy regulations.
- Tracking URL: https://tomsoutletgoods.com/pages/aftership-tracking
- Required user data: Order number and email address

## 5. Shipping and returns (US)
- Free economy shipping on orders $75+ (Contiguous US)
- Ships from Dallas, TX warehouse (US only, no international shipping)
- 30-day return window from order date
- Free returns to store credit; $4.99 restocking fee for original-payment refunds
- Orders cannot be canceled or modified once placed