Ordering for AI agents

0Identify yourself

Send X-Agent-Name: YourAssistant/1.0 on every request. Orders you place are marked as placed by an agent, so our team knows how they came in. The store can pause agent orders; you then get a 403 with a message you can show the person. GET /api/checkout/status says whether the store is taking orders.

1Find products

Read the feed (refreshed every 5 minutes). Each product has its id, price in rupees and, for products with quality options, an options list with each option's id and price. Only offer products whose availability is in_stock.

curl https://osws-backend.vercel.app/api/feed/products.json -H "X-Agent-Name: YourAssistant/1.0"

2Start a cart

Keep cart.session_token. It is the only key to this cart, so don't share it.

curl -X POST https://osws-backend.vercel.app/api/cart -H "X-Agent-Name: YourAssistant/1.0"

3Add items

Use the option's id as variantId (leave it out for products without options). At most 10 of any one item; for larger quantities send the person to our Bulk Orders form.

curl -X POST https://osws-backend.vercel.app/api/cart/SESSION_TOKEN/items \
  -H "Content-Type: application/json" -H "X-Agent-Name: YourAssistant/1.0" \
  -d '{"productId":"PRODUCT_ID","variantId":"OPTION_ID","qty":2}'

4Say who is buying

The buyer's name and 10-digit Indian mobile number, exactly as they gave them to you for this order. The phone number is how they track the order later.

curl -X POST https://osws-backend.vercel.app/api/cart/SESSION_TOKEN/identify \
  -H "Content-Type: application/json" -H "X-Agent-Name: YourAssistant/1.0" \
  -d '{"name":"Asha Patel","phone":"9876543210"}'

5Check delivery and its cost

Delivery is calculated from the pincode and is never free. There is no separate Cash on Delivery fee, but the delivery charge can differ between COD and online payment, so quote with the method the person will use. codAvailable says whether Cash on Delivery can be used for this pincode.

curl -X POST https://osws-backend.vercel.app/api/shipping/quote \
  -H "Content-Type: application/json" -H "X-Agent-Name: YourAssistant/1.0" \
  -d '{"sessionToken":"SESSION_TOKEN","pincode":"400001","paymentMethod":"upi"}'

6Place the order

Confirm the items, delivery charge and total with the person first. Prices and delivery are always taken from our server, never from your request.

• Cash on Delivery ("paymentMethod":"cod"): the order is placed and the person pays when it arrives. Only where the courier offers COD, for orders up to ₹5,000, and at most 2 undelivered COD orders per phone number.
• Online payment (upi, card, netbanking or wallet): the response has payUrl and payBy. Give the link to the person; they open it and pay on our page with Razorpay (no login). The items are held for 15 minutes. If they don't pay by payBy, the order expires and nothing is charged. Never collect card or UPI details yourself.

curl -X POST https://osws-backend.vercel.app/api/checkout/order \
  -H "Content-Type: application/json" -H "X-Agent-Name: YourAssistant/1.0" \
  -d '{"sessionToken":"SESSION_TOKEN","paymentMethod":"upi",
       "shippingAddress":{"name":"Asha Patel","phone":"9876543210","line1":"12 Marine Lines",
       "city":"Mumbai","state":"Maharashtra","pincode":"400001"}}'

7Follow the order

While an online payment is open, GET /api/checkout/pay/PAY_TOKEN (the t value in payUrl) gives its state: payable, paid, expired or cancelled. Check at most every 10 seconds. After that, track the order with its number and the buyer's phone.

curl -X POST https://osws-backend.vercel.app/api/track-order \
  -H "Content-Type: application/json" -H "X-Agent-Name: YourAssistant/1.0" \
  -d '{"orderNumber":"ORDER_NUMBER","phone":"9876543210"}'

Limits

Limits are per IP address, per hour. Going over one returns 429: wait, don't retry in a loop.

• Orders: 30; unpaid online orders per cart: 3
• New carts: 60; cart changes: 300
• Pincode checks: 120; delivery quotes: 120
• Order tracking: 20 (and 8 per order number); payment status: 300; product feed: 120

Errors are always {"error":{"message":"…","status":…}}. The message is written for people, so you can pass it on.