> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI shopping agents

> Let an AI assistant find Khaime stores, browse their products and start a checkout for a shopper. No key needed.

# 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

```bash theme={null}
curl -X POST https://api.khaime.com/api/v1/agent/checkout \
  -H "Content-Type: application/json" \
  -H "X-Actor-Type: agent" \
  -H "X-Actor-Id: my-shopping-agent" \
  -d '{
    "product_id": 4821,
    "customer_name": "Ada Obi",
    "customer_email": "ada@example.com",
    "currency": "USD",
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cart"
  }'
```

| Field | Required | What it is |
| - | - | - |
| `product_id` | Yes | From `/products`. |
| `customer_name` | Yes | The shopper's full name. |
| `customer_email` | Yes | Where the receipt goes. |
| `currency` | No | The currency the shopper pays in. Defaults to the product's currency. |
| `mode` | No | `redirect` (default) returns a `payment_url`. `embedded` returns what you need to show Khaime's payment form in your own page. |
| `subscription_frequency` | For subscriptions | The billing interval key from the product. |
| `success_url`, `cancel_url` | No | Where the shopper lands after paying or giving up. |
| `metadata` | No | Your own reference, returned with the order. |

The response:

```json theme={null}
{
  "success": true,
  "checkout": {
    "session_id": "pi_...",
    "payment_url": "https://...",
    "amount_cents": 4500,
    "currency": "USD",
    "formatted_amount": "USD 45.00",
    "status": "pending",
    "expires_at": "2026-11-08T12:30:00.000Z"
  }
}
```

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:

| Code | Meaning |
| - | - |
| `STORE_NOT_FOUND` | The store doesn't exist or isn't open to agents. |
| `PRODUCT_NOT_FOUND` | No published product with that id. |
| `MISSING_REQUIRED_FIELD` | A required field is missing; the message names it. |
| `RATE_LIMIT_EXCEEDED` | Over 1,000 requests this hour from your IP. Wait for the reset time. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.