> ## 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.

# Show your store's data

> Where each kind of Khaime data can appear in Lovable and other AI website builders: products on your website, private numbers through a server function or in chat.

# Show your store's data

Use this page when you ask an AI website builder to show something from Khaime. If you are the AI builder, follow it exactly.

## Where each thing can appear

Your website is public. Anything in its code or pages can be read by anyone, so private numbers never go on a public page.

| What you want to show | On a public page | On a private page, through a server function | In the builder's chat | In your Khaime dashboard |
| - | - | - | - | - |
| Products, prices, photos, options, stock | Yes | Yes | Yes | Yes |
| Currency picker, cart, checkout | Yes | No | No | No |
| Sales, revenue, refunds | **No** | Yes | Yes | Yes |
| Orders and customers | **No** | Yes | Yes | Yes |
| Visitors and conversion rate | **No** | Yes | Yes | Yes |
| Traffic sources and top countries | **No** | Yes | Yes | Yes |
| Checkout funnel and where shoppers drop off | **No** | Yes | Yes | Yes |
| Product views and adds to cart | **No** | Yes | Yes | Yes |
| Live visitors | **No** | Yes | Yes | Yes |
| Abandoned carts | **No** | No | No | Yes |

To show private numbers on a page, follow [Show private numbers from a server function](#show-private-numbers-from-a-server-function). To ask about them instead, follow [Ask about everything else in chat](#ask-about-everything-else-in-chat).

## Show products on your website

These run in the browser and use the public store key already set up in `src/lib/khaime.ts`. If that file does not exist, see [Add Khaime to a website you already built](https://docs.khaime.com/ai-builders/lovable.md#add-khaime-to-a-website-you-already-built).

### Product list

```ts theme={null}
import { khaime } from '@/lib/khaime';

// sort: 'newest' | 'price_asc' | 'price_desc' | 'popular'
const products = await khaime.getProducts({ limit: 24, offset: 0, sort: 'newest' });
```

Add `categorySlug: 'shoes'` to show one category. `getProducts` returns an array.

| Show | Use |
| - | - |
| Name | `product.title` |
| Photo | `product.thumbnail`, or `product.images` for a gallery |
| Price | `product.formatted_price`, exactly as given |
| Old price, crossed out | `product.formatted_slash_price`, when `product.is_slash_price` is `true` |
| Description | `product.description` |
| Pre-order label | when `product.is_preorder` is `true` |

Never add, convert or discount a price yourself.

### Pre-orders

A pre-order is sold now and shipped later. `product.is_preorder` says which products are pre-orders, and `product.preorder` has the details (it is `null` for everything else):

| Field | Meaning |
| - | - |
| `preorder.open` | `true` while it can still be ordered. `false` once the order-by date has passed or every place is taken. |
| `preorder.ships_on` | Expected ship date (ISO), or `null` when the business set none |
| `preorder.order_by` | Last moment to pre-order (ISO), or `null` when there is no deadline |
| `preorder.places_left` | Places left, or `null` when there is no limit |

Show a "Pre-order" label and the dates when they are set, and label the button "Pre-order" instead of "Add to cart". When `preorder.open` is `false`, disable the button and say "Pre-orders closed". Checkout refuses a closed pre-order anyway.

### One product and its options

```ts theme={null}
const product = await khaime.getProduct(id);
```

Each entry in `product.variants` is one option, such as a size or colour:

| Show | Use |
| - | - |
| Option name | `variant.name` |
| Full price of that option | `variant.formatted_price` |
| Disable the option | when `variant.sold_out` is `true` |

Work out whether a product is sold out from its options first, because stock can be kept on the options alone:

```ts theme={null}
const soldOut = product.variants?.length
  ? product.variants.every((v) => v.sold_out)
  : product.stock != null && product.stock <= 0;
```

### Add to cart or Buy now

`product.type` decides which button to show:

```ts theme={null}
if (product.type === 'physical_product') {
  const cart = khaime.cart();
  cart.addItem(product, quantity, pickedVariant); // leave pickedVariant out if there are no options
  // The cart's Checkout button goes to your own /checkout page:
  navigate('/checkout');
} else {
  // Anything else skips the cart. The element must already be on the page.
  await khaime.payButton('#buy-button', { productId: product.id, label: 'Buy now' });
}
```

Show the cart with `cart.getItems()`, `cart.getItemCount()` and `cart.subscribe(callback)`. Remove a line with `cart.removeItem(productId, variant.id)`.

### Checkout page

Checkout is a normal page of your website, at `/checkout`, with your own header and footer. Khaime fills one element on it with the checkout: the shopper's details, the delivery address and payment. Prices, shipping and fees come from Khaime.

```tsx theme={null}
export default function CheckoutPage() {
  const navigate = useNavigate();

  useEffect(() => {
    let unmount: (() => void) | undefined;
    khaime.mountCartCheckout('#khaime-checkout', {
      onSuccess: () => navigate('/thank-you'),
    }).then((u) => { unmount = u; });
    return () => unmount?.();
  }, []);

  return (
    <main>
      <h1>Checkout</h1>
      <div id="khaime-checkout"></div>
    </main>
  );
}
```

* Call it from `useEffect`, so the element is on the page first.
* Mounting twice (React StrictMode) is fine: the second replaces the first.
* An empty cart shows "Your cart is empty." Pass `emptyMessage` to change the words.
* On the payment step a Back button returns to the details, with nothing lost.
* `khaime.openCartCheckout({ onSuccess })` still opens the same checkout as a popup, if you prefer one.

**Match your brand.** The checkout's buttons and highlights use your colour and your fonts when you set these in your site's CSS:

```css theme={null}
:root {
  --ks-primary: #1f4d3a;            /* buttons, links, the active step */
  --ks-primary-contrast: #ffffff;   /* text on those buttons */
  --ks-host-font-body: 'Inter', sans-serif;
  --ks-host-font-display: 'Fraunces', serif; /* step titles */
}
```

Everything else (white card, grey lines, error red) stays as Khaime sets it, so the payment step always looks trustworthy.

Buy now on an event charges the product's price. It has no ticket picker.

### Currency picker

```ts theme={null}
const { current, options, canSwitch } = await khaime.getCurrencies();
```

* `canSwitch` is `true`: show a picker listing `options`. When one is picked, call `await khaime.setCurrency(code)`, then load the products again.
* `canSwitch` is `false`: show no picker. The store sells in one currency.

## Show private numbers from a server function

Traffic, funnels, sales, orders and customers come from the [store data endpoints](https://docs.khaime.com/api-reference/store-data/overview.md). They need a private `pk_` key, so they run on a server and never in the browser. If your project has no server functions, this is not possible there. Say so and use chat.

> [!WARNING]
>
> A `pk_` key opens orders, customers and payouts. Store it only as a server secret. Do not put it in website code, a `VITE_` or `NEXT_PUBLIC_` variable, or the chat. The public `pub_` key does not work on these endpoints.

**1. Add the key as a server secret**

Ask the owner to copy a key from **Settings → API & Integrations** in the Khaime dashboard and add it to the project's server secrets as `KHAIME_API_KEY`. Use a `pk_sandbox_` key while testing and a `pk_live_` key for real numbers. See [Authentication](https://docs.khaime.com/api-reference/authentication.md).

**2. Add a server function**

The function holds the key, reads one endpoint, and returns only what the page shows. Check that the person is signed in as the owner before reading anything.

```ts theme={null}
// Runs on the server. Never import this into a page.
export async function getStoreSummary(request: Request) {
  await requireOwner(request); // your project's own login check

  const response = await fetch(
    'https://api.khaime.com/api/v1/analytics/headline?range=30d',
    { headers: { 'X-API-Key': process.env.KHAIME_API_KEY! } }
  );
  const body = await response.json();

  if (!response.ok) {
    // Switch on error_code. Do not show the numbers as 0.
    return { error: body.error_code };
  }

  const { revenue, currency, visitors, conversion_rate } = body.data;
  return { revenue, currency, visitors, conversion_rate };
}
```

Use the server secret mechanism your project has. The variable may not be `process.env`.

**3. Call your function from the page**

The page calls your function, not Khaime. The browser never sees the key.

```ts theme={null}
const summary = await fetch('/api/store-summary').then((r) => r.json());
```

**4. Show the numbers correctly**

```ts theme={null}
// currency is null until the store has a sale.
const revenue = summary.currency
  ? (summary.revenue.current / 100).toLocaleString(undefined, {
      style: 'currency',
      currency: summary.currency,
    })
  : 'No sales yet';
const visitors = summary.visitors.tracked ? summary.visitors.current : 'Not tracked';
const conversion = summary.conversion_rate === null ? 'Not measurable' : `${summary.conversion_rate}%`;
```

Show nothing as 0 unless Khaime returned 0. If you get `BUSINESS_FEATURE_UNAVAILABLE`, tell the owner this report needs Store Pulse on their plan.

| You want | Endpoint | Plan |
| - | - | - |
| Revenue, visitors, conversion rate | [`/analytics/headline`](https://docs.khaime.com/api-reference/store-data/headline) | Every plan |
| Who is on the website now | [`/analytics/live`](https://docs.khaime.com/api-reference/store-data/live) | Every plan |
| Where shoppers drop off | [`/analytics/funnel`](https://docs.khaime.com/api-reference/store-data/funnel) | Store Pulse |
| Where visitors come from | [`/analytics/sources`](https://docs.khaime.com/api-reference/store-data/sources) | Store Pulse |
| Where visitors are | [`/analytics/countries`](https://docs.khaime.com/api-reference/store-data/countries) | Store Pulse |
| Views, adds to cart and orders per product | [`/analytics/products`](https://docs.khaime.com/api-reference/store-data/products) | Store Pulse |
| Revenue, refunds and orders for dates | [`/analytics/sales`](https://docs.khaime.com/api-reference/store-data/sales) | Every plan |
| Orders | [`/analytics/orders`](https://docs.khaime.com/api-reference/store-data/list-orders) | Every plan |
| One order | [`/analytics/orders/{order_id}`](https://docs.khaime.com/api-reference/store-data/get-order) | Every plan |
| Customers | [`/analytics/customers`](https://docs.khaime.com/api-reference/store-data/list-customers) | Every plan |

Keep these pages behind a login. Your server function's answer is public if the function does not check who is asking. Customer names and emails are personal information, so show them only to the owner and their staff.

Cache each answer on your server for about a minute. Requests count against the key's hourly limit, and a busy page can use it up.

## Ask about everything else in chat

Sales, traffic and funnels come from [connecting Khaime to the builder's chat](https://docs.khaime.com/ai-builders/lovable-chat.md). The builder reads the answer and tells you. The numbers stay in chat.

| You want | Ask | Khaime tool |
| - | - | - |
| Revenue, refunds, orders, average order value | "How did my sales do this month compared with last month?" | `khaime_get_sales_summary` |
| Visitors, completed checkouts, conversion rate | "How much traffic did I get in the last 7 days?" | `khaime_get_storefront_traffic` |
| Where shoppers drop off | "Where do shoppers leave before paying?" | `khaime_get_checkout_funnel` |
| Where visitors come from | "Which channels bring buyers?" | `khaime_get_traffic_sources` |
| Where visitors are | "Which countries buy the most?" | `khaime_get_top_countries` |
| Views, adds to cart and orders per product | "Which products get viewed but not bought?" | `khaime_get_product_performance` |
| Who is on the website now, and what is in their carts | "Who is on my store right now?" | `khaime_get_live_visitors` |
| Orders | "Show unpaid orders from this week" | `khaime_search_orders`, `khaime_get_order` |
| Products and stock | "What is running low?" | `khaime_search_products`, `khaime_get_low_stock` |
| Customers | "Who are my top customers?" | `khaime_search_customers` |
| Store name and currency | "Which store are you connected to?" | `khaime_get_business_profile` |

Traffic, funnel, sources, countries and product performance take a range: `today`, `7d`, `30d` or `90d`. The default is `30d`. Sales and orders take dates as `YYYY-MM-DD`. Tools return plain sentences, not JSON.

### Read the answers correctly

* **Not tracked is not zero.** A funnel step marked *not tracked* has nothing measuring it. Do not report it as 0.
* **Not measurable is not zero.** The same goes for a conversion rate that comes back as *not measurable*.
* **The funnel counts visits, not people.** A shopper who comes back twice is two visits.
* **Currencies are never added together.** Other currencies are listed separately from the main total.
* **Visitor counts include testing.** They are not split into live and sandbox. Revenue is.

## Traffic is tracked by itself

On a website using the Khaime script, you add no tracking code. It records visitors, sources, countries, product views, adds to cart and checkouts. Results appear in chat and in **Store Pulse** in your dashboard.

Sites built on the REST API set this up differently: see [Store Pulse for API integrations](https://docs.khaime.com/store-pulse/api-integrations.md).

## Never do this

* Put a `pk_` key or a chat connection link in website code.
* Call the store data endpoints from the browser.
* Show traffic, sales, orders or customers on a page without a login.
* Build a database to hold copies of Khaime data.
* Copy products or numbers into the code. Load them when the page opens.
* Do sums on prices, or show a figure Khaime did not return.


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