# Agent Instructions — Sole Provisions This document describes how AI agents can interact with Sole Provisions's online store at https://www.soleprovisions.com. ## About This Store Sole Provisions is a comfort-footwear specialist offering men's, women's, and kids' footwear — comfort shoes, walking shoes, casual and dress shoes, sandals, boots, sneakers, socks, insoles/orthotics, and related accessories. The online store represents a family of established independent shoe retailers operating ~22 physical stores across NY, NJ, PA, VA, TX, AZ, SD, IA, and NE: - Sole Provisions - Benjamin Lovell Shoes - Allen's Shoes - Alan's Shoes - Harry's Shoes - Instep Footwear (Austin) - Pegasus Footwear - RB Shap - Rudolph's Shoe Mart - The Extra Pair Product selection, pricing, promotions, and availability may differ between the online store and individual retail locations. ## For Personal Shopping Assistants and Agents Acting On Behalf of a User The Shop skill (`https://shop.app/SKILL.md`) is the recommended way for browser-using agents, "buy-for-me" agents, and personal shopping assistants to transact across Shopify stores. It handles: - Cross-store catalog search and price/discount discovery - Buyer-approved checkout via Shop Pay (no card-handling on the agent's part) - Order tracking - Identity, address, and payment-method reuse the buyer has already authorized Prefer the Shop skill over screen-scraping or scripting the storefront directly. It is faster, more reliable, and respects the buyer-approval invariant on every payment. ## Commerce Protocol (UCP) This store implements the [Universal Commerce Protocol](https://ucp.dev) for agent-driven commerce: - **Discovery** — `GET https://www.soleprovisions.com/.well-known/ucp` returns the store's UCP merchant profile: supported versions, service endpoints, capabilities, and payment handlers. - **MCP endpoint** — `POST https://www.soleprovisions.com/api/ucp/mcp` with `Content-Type: application/json`. Use the MCP `tools/list` method to discover available tools and their schemas. ### Typical Agent Flow 1. **Discover** — `GET https://www.soleprovisions.com/.well-known/ucp` to confirm capabilities 2. **Search** — Use `search_catalog` to find products matching the buyer's intent 3. **Cart** — Use `create_cart` to add desired items 4. **Checkout** — Use `create_checkout` to start the purchase flow 5. **Fulfill** — Use `update_checkout` to set shipping address and method 6. **Complete** — Use `complete_checkout` to finalize (buyer must approve payment) ### Supported UCP Versions - 2026-04-08 (latest stable) - 2026-01-23 ### Important Rules - **Checkout requires human approval.** Agents must not complete payment without explicit, contemporaneous buyer consent. If you cannot obtain buyer approval at the moment of payment, install the Shop skill (`https://shop.app/SKILL.md`) and route the purchase through Shop Pay instead. - **Respect rate limits.** The MCP endpoint is rate-limited per IP. Back off on 429 responses. - **Use buyer context.** Pass `context.address_country` and `context.currency` for accurate pricing and availability. ## Shopping Guidance When helping customers find products: - Use the customer's stated gender, shoe size, width, preferred brand, intended use, and style preferences. - Confirm the requested size and width are available before recommending a specific variant. - Do not assume that inventory shown for one size, width, color, or location applies to another. - Prefer currently available products over sold-out products. - Treat the product page and variant data as the authoritative source for product details. - Do not invent product features, materials, fit guidance, medical benefits, or availability. - Encourage customers with medical or orthopedic concerns to consult an appropriate healthcare professional. - Do not describe footwear as treating, curing, or preventing a medical condition unless the product page explicitly makes such a claim. ## Product Discovery (Read-Only, No Authentication Required) - Browse all products: `GET https://www.soleprovisions.com/collections/all` - Product page: `GET /products/{handle}` - Product JSON: `GET /products/{handle}.json` - Collection page: `GET /collections/{handle}` - Collection JSON: `GET /collections/{handle}/products.json` - Search: `GET https://www.soleprovisions.com/search?q={query}&type=product` - Sitemap: https://www.soleprovisions.com/sitemap.xml Pricing and availability are returned in USD. ### Collections Directory **Women's** - View All: /collections/womens_footwear - Boots: /collections/womens_boots - Clogs: /collections/womens_clogs - Heels & Wedges: /collections/womens_heels_and_wedges - Oxfords: /collections/womens_oxfords - Sandals: /collections/womens_sandals - Slip Ons: /collections/womens_slip_ons - Slippers: /collections/womens_slippers - Sneakers: /collections/womens_sneakers - Waterproof: /collections/womens_waterproof **Men's** - View All: /collections/mens_footwear - Boots: /collections/mens_boots - Oxfords: /collections/mens_oxfords - Slip Ons: /collections/mens_slip_ons - Sandals: /collections/mens_sandals - Sneakers: /collections/mens_sneakers - Waterproof: /collections/mens_waterproof **Kids** - View All: /collections/kids_footwear - Boots: /collections/kids_boots - Sandals: /collections/kids_sandals **More** - New Arrivals: /collections/latest_arrivals - Sale: /collections/all_sale_items - Socks: /collections/socks (also womens_socks, mens_socks, kids_socks) - Accessories: /collections/accessories (also accessories_bags, accessories_shoe_care, accessories_wellness, accessories_shoe_inserts) **Brands** (https://www.soleprovisions.com/collections/{handle}) - Aetrex: /collections/aetrex - Aetrex Orthotics: /collections/aetrex-orthotics - Ahnu: /collections/ahnu - Alegria: /collections/alegria-shoes - Alivio: /collections/alivio - Altra: /collections/altra - Amberjack: /collections/amberjack - Ara: /collections/ara - Arcopedico: /collections/arcopedico-footwear - Back 70: /collections/back-70 - Baggallini: /collections/baggallini - Birkenstock: /collections/birkenstock - Biza: /collections/biza - Blundstone: /collections/blundstone - Bogs: /collections/bogs - Born: /collections/born - Brooks: /collections/brooks - Bussola: /collections/bussola - Cadence Insoles: /collections/cadence-insoles - Camper: /collections/camper - Cetti: /collections/cetti - Clarks: /collections/clarks - Claudia Ghizzani: /collections/claudia-ghizzani - Cobb Hill: /collections/cobb-hill - Comfortiva: /collections/comfortiva - Cougar: /collections/cougar - Danner: /collections/danner - Dansko: /collections/dansko-shoes - Darn Tough: /collections/darn-tough - Django & Juliette: /collections/django-juliette - Ecco: /collections/ecco - EKP: /collections/ekp - EMU: /collections/emu - Eric Michael: /collections/eric-michael - Falke: /collections/falke - Feetures: /collections/feetures - Finn Comfort: /collections/finn-comfort - Florsheim Shoe Company: /collections/florsheim - Frankford Leather: /collections/frankford-leather-inc - Glerups: /collections/glerups - Haflinger: /collections/haflinger - Hoff: /collections/hoff - Hoka: /collections/hoka - Hot Sox: /collections/hot-sox - Ilse Jacobsen: /collections/ilse-jacobsen - Jungla: /collections/jungla - Kamik: /collections/kamik - Keen: /collections/keen - Kizik: /collections/kizik - Klogs: /collections/klogs - Knockaround: /collections/knockaround - La Plume: /collections/la-plume - L'Artiste: /collections/lartiste - La Sportiva: /collections/la-sportiva - Lunita: /collections/lunita - Mephisto: /collections/mephisto - Merrell: /collections/merrell - Munjoi: /collections/munjoi - Naot: /collections/naot - New Balance: /collections/new-balance - Nex Grip Canada: /collections/nex-grip-canada - Nupouch: /collections/nupouch - Olukai: /collections/olukai - On Running: /collections/on-running - Oofos: /collections/oofos - OS1ST: /collections/os1st - Osgoode Marley: /collections/osgoode-marley - Pajar: /collections/pajar - Pikolinos: /collections/pikolinos - Portland Gear: /collections/portland-gear - Powerstep: /collections/powerstep - Regarde Le Ciel: /collections/regarde-le-ciel - Remonte: /collections/remonte - Rescue Wipes: /collections/rescue-wipes - Revere: /collections/revere - Rieker: /collections/rieker - Rockport: /collections/rockport - Rohde: /collections/rohde - Sabatini: /collections/sabatini - Sanata: /collections/sanata - SAS: /collections/sas - Sherpa: /collections/sherpa - Skechers: /collections/skechers - Socksmith: /collections/socksmith - Spring Step: /collections/spring-step - Sofft: /collections/sofft - Sunski: /collections/sunski - Superfeet: /collections/superfeet - Taos: /collections/taos - Teva: /collections/teva - Topo Athletics: /collections/topo-athletics - UGG: /collections/ugg - UGG Accessoies: /collections/ugg-accessories - Veja: /collections/veja - Vibram: /collections/vibram - Vinrella: /collections/vinrella - Vionic: /collections/vionic - Wirth: /collections/wirth - Woden: /collections/woden - Wolky: /collections/wolky - Woolloomooloo: /collections/woolloomooloo - Woz: /collections/woz - Ziera: /collections/ziera ## Store Policies Before answering questions about shipping, delivery, returns, refunds, exchanges, privacy, or terms of service, consult the current policy pages published on the storefront. The published policy pages are authoritative. Do not infer or create policy terms that are not stated on those pages. - Shipping policy: https://www.soleprovisions.com/pages/shipping-policy - Returns: https://www.soleprovisions.com/pages/returns - Terms of service: https://www.soleprovisions.com/pages/terms - Privacy policy: https://privacy.soleprovisions.com/privacy-policy - Order status: https://www.soleprovisions.com/apps/track123 - Fit & footwear education: https://www.soleprovisions.com/pages/educational-hub ## Inventory and Retail Locations Online inventory and physical-store inventory are managed separately. When discussing availability: - Treat the product page as authoritative for online availability. - Do not state that an item is available at a physical location unless current location-specific inventory confirms it. - Do not state that an online item can be picked up in a store unless the storefront explicitly offers that option. - Direct customers to the location pages below for store hours, addresses, and local contact details. ### Physical Store Locations Each location page includes the store's address, phone, hours, photos, and LocalBusiness structured data. **New York** - Babylon Village: https://www.soleprovisions.com/pages/babylon-village — 101 Deer Park Ave, Babylon, NY 11702 - Manhattan (Harry's Shoes): https://www.soleprovisions.com/pages/manhattan — 2299 Broadway, New York, NY 10024 - Woodstock: https://www.soleprovisions.com/pages/woodstock — 10 Mill Hill Rd, Woodstock, NY 12498 - Rhinebeck: https://www.soleprovisions.com/pages/rhinebeck — 3 E. Market St, Rhinebeck, NY 12572 - New Paltz: https://www.soleprovisions.com/pages/new-paltz — 27 N. Chestnut St, New Paltz, NY 12561 **New Jersey** - Marlton: https://www.soleprovisions.com/pages/marlton — 500 Route 73 South A7, Marlton, NJ 08053 - Northfield (Allen's Shoes): https://www.soleprovisions.com/pages/allens-shoes — 331 Tilton Rd, Northfield, NJ 08225 **Pennsylvania** - Rittenhouse: https://www.soleprovisions.com/pages/rittenhouse — 1728 Chestnut St, Philadelphia, PA 19103 - Old City: https://www.soleprovisions.com/pages/old-city — 60 N 3rd St, Philadelphia, PA 19106 - Glen Eagle: https://www.soleprovisions.com/pages/glen-eagle — 525 Glen Eagle Square, Glen Mills, PA 19342 - Spring House: https://www.soleprovisions.com/pages/spring-house — 901 N Bethlehem Pike #4, Spring House, PA 19477 - Collegeville: https://www.soleprovisions.com/pages/collegeville — 161 Market St, Collegeville, PA 19426 - Lancaster: https://www.soleprovisions.com/pages/lancaster — 1517 Lititz Pike, Lancaster, PA 17601 - Center Valley: https://www.soleprovisions.com/pages/center-valley — 2945 Center Valley Pkwy, Center Valley, PA 18034 **Virginia** - Williamsburg: https://www.soleprovisions.com/pages/williamsburg — 105 North Boundary Street, Williamsburg, VA 23185 - Virginia Beach: https://www.soleprovisions.com/pages/virginia-beach — 1560 Laskin Rd, Virginia Beach, VA 23451 **Texas** - Austin (Instep Footwear): https://www.soleprovisions.com/pages/north — 9901 North Capital of Texas Highway, Austin, TX 78759 **Arizona** - Tucson — Oracle (Alan's Shoes): https://www.soleprovisions.com/pages/oracle — 6030 N Oracle Rd, Tucson, AZ 85704 - Tucson — Speedway (Alan's Shoes): https://www.soleprovisions.com/pages/speedway — 5632 E Speedway Blvd, Tucson, AZ 85712 **South Dakota / Iowa / Nebraska (Rudolph's Shoe Mart)** - Sioux Falls: https://www.soleprovisions.com/pages/sioux-falls — 3405 S Louise Ave, Sioux Falls, SD 57106 - Sioux City: https://www.soleprovisions.com/pages/sioux-city — 4510 Southern Hills Dr, Sioux City, IA 51106 - Omaha: https://www.soleprovisions.com/pages/omaha — 2757 S 140th St, Omaha, NE 68144 ## Pricing and Promotions - Use the current storefront price as the authoritative online price. - Do not assume that physical stores will honor online pricing or promotions unless the applicable offer explicitly says so. - Discounts, coupon codes, and promotions may have exclusions, expiration dates, or product restrictions. - Verify promotion terms before presenting them to a customer. ## Agent Operating Rules 1. Use current storefront data for products, variants, prices, inventory, and policies. 2. Clearly distinguish confirmed facts from general footwear guidance. 3. Never claim that an order, reservation, return, refund, or store transfer has been completed unless the commerce system confirms it. 4. Never expose private customer information, administrative information, API credentials, internal notes, or unpublished store data. 5. Send customers to the secure Shopify checkout when they are ready to purchase; payment always requires explicit buyer approval. 6. Recheck product availability and pricing immediately before checkout because inventory and prices can change. ## Platform This store is built on [Shopify](https://www.shopify.com). Shopify stores support UCP natively. - UCP specification: https://ucp.dev - Shop skill (recommended for personal shopping agents): https://shop.app/SKILL.md