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
Connect a compatible MCP client to https://www.onaholestation.com/api/mcp to search products and read buying guides, or prepare a cart for user confirmation. Some clients need you to add this connection first. MCP discovery.
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 48 hours and does not reserve prices or stock. The same authorized browser can continue an adopted cart for up to 7 days from preparation; an unclaimed expired link needs the user to request a new cart. 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. - When enabled, the user can separately authorize a saved shipping preference in their account and status access for this checkout on the handoff page. Send only the private preference reference, never a raw address. Status credentials require explicit consent, can be revoked, and only allow read access to this checkout and its order. Keep all credentials private and out of URLs. These permissions do not authorize payment or order submission.
