AI shopping agents
The agent API lets an AI assistant (ChatGPT, Claude, Gemini, Khai or your own agent) shop Khaime stores for a person: find a store, browse its products and start a checkout. The shopper then pays on Khaime’s normal payment page, so the store is paid exactly as it is for any other sale. Base URL:https://api.khaime.com/api/v1/agent
No API key is needed. Requests are limited to 1,000 an hour per IP address; every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
Send X-Actor-Type: agent on every request, plus X-Actor-Id with your agent’s name if you like. This tells the store an AI agent started the order.
Which stores are open to agents
A Khaime store is open to agents when its plan includes AI shopping assistants and it has published products. Stores on plans without it, and stores that asked us to close them to agents, do not appear and answerSTORE_NOT_FOUND.
The flow
1
Learn what the API can do
GET /capabilities describes every call. Each response also has next_actions (the calls that make sense next) and instructions in plain words, so an agent can follow along without this page.2
Find a store
GET /stores?query=ankara&limit=20&offset=0 lists open stores with a name, logo, description and product count.3
Browse products
GET /products?store_id=123&limit=20 lists a store’s products. Add currency=USD for prices in the shopper’s currency and product_type (physical, digital, service, live_event or bundle) to filter. GET /products/:product_id returns one product.4
Start the checkout
POST /checkout with the product and the shopper’s name and email. The response has a payment_url: give it to the shopper to pay.5
Check it was paid
GET /checkout/:session_id returns the status: pending, completed (paid), failed, cancelled or expired.Start a checkout
The response:
What the agent never does
- It never sees card details. The shopper pays on Khaime’s payment page. Agents paying on the shopper’s behalf with a scoped payment token is coming next.
- It never changes the price. The price comes from the store, in the currency asked for. Show
formatted_amountas it is.
Errors
Errors have acode and a plain message. The ones to handle:
