AI shopping guide
Search products, read available variants, then prepare a cart when the user asks to buy. The user reviews the cart and completes payment.
Product search & cart instructionsAPI reference & examplesBrand stories & buying guides
How an Agent can search and prepare a cart
- Search this site's JSON catalog:
GET /api/agent/products?q={keyword}&country=ca&locale=en-CA&limit=5Replace keyword with a URL-encoded search term (2-100 characters), and use the user's country and an enabled locale.
- Follow a result's
detail_api_url to read its variants. Select the user's desired variant_id with purchasable=true. If reading a product page, use its Markdown alternate or the JSON detail route /api/agent/products/{handle}?country=ca&locale=en-CA. - Prepare the selected items:
POST /api/agent/checkout-sessions. No authentication is required. Send Content-Type: application/json and a unique Idempotency-Key (8-128 characters); reuse the same key and body only when retrying an identical request.{"country":"ca","locale":"en-CA","items":[{"variant_id":"variant_REPLACE_WITH_USER_SELECTED_VARIANT","quantity":1}]}
Replace the variant placeholder and country/locale before sending. Up to 10 distinct variants, quantity 1-5 each. Prices and availability are checked again by the server.
If the response is checkout_result_unknown, ask the user to verify the outcome before trying again. Do not automatically use a new key. For temporary failures, retry the same key and body.
- Return the successful response's
checkout_url to the user. The link expires after 15 minutes. The user opens it, reviews and confirms the cart, then completes checkout. Agents must not submit orders, initialize payment, or send payment credentials. Reading or indexing pages alone should not create carts.