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.
To show private numbers on a page, follow Show private numbers from a server function. To ask about them instead, follow 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 insrc/lib/khaime.ts. If that file does not exist, see Add Khaime to a website you already built.
Product list
categorySlug: 'shoes' to show one category. getProducts returns an array.
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):
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
product.variants is one option, such as a size or colour:
Work out whether a product is sold out from its options first, because stock can be kept on the options alone:
Add to cart or Buy now
product.type decides which button to show:
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.
- 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
emptyMessageto 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.
Currency picker
canSwitchistrue: show a picker listingoptions. When one is picked, callawait khaime.setCurrency(code), then load the products again.canSwitchisfalse: 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. They need a privatepk_ 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.
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.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.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.
4
Show the numbers correctly
BUSINESS_FEATURE_UNAVAILABLE, tell the owner this report needs Store Pulse on their 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. The builder reads the answer and tells you. The numbers stay in chat.
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.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.
