Skip to main content

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 answer STORE_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:
Amounts are in cents (minor units): divide by 100 to show them.

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_amount as it is.

Errors

Errors have a code and a plain message. The ones to handle: