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://www.toms.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://www.toms.com/products/{product-handle}.json
• Example: https://www.toms.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://www.toms.com/search?q={search_term}
• Example: https://www.toms.com/search?q=black+canvas+alpargata

Main product collections

• Women's shoes: https://www.toms.com/collections/womens-shoes
• Men's shoes: https://www.toms.com/collections/mens-shoes
• Kids' shoes: https://www.toms.com/collections/kids-shoes
• Sale and clearance: https://www.toms.com/collections/sale

Knowledge and support

• Full brand knowledge base: https://www.toms.com/llms-full.txt
• FAQ: https://www.toms.com/pages/faq
• Contact: https://www.toms.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://www.toms.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