Shopify

​

Overview

The KaireonAI Personalization app for Shopify shows a personalized, ranked offer on four storefront surfaces — the product page, cart, home page, and the Thank You page — and closes the loop back to KaireonAI’s decisioning engine with impressions, clicks, add-to-carts, purchases, and refunds. It requires no code changes to your theme beyond adding app blocks through the theme editor.

​

What gets installed

​

Install

1. Install the app from the Shopify App Store listing (or, for a private/custom app during development, via the install link your KaireonAI contact provides).
2. Approve the requested scopes. The app requests read_products, read_orders, and read_inventory only — it never writes to your product catalog or orders. Product edits you make inside KaireonAI’s embedded admin only affect KaireonAI’s own copy of your catalog (curation fields like activation, per-surface placement, and per-offer weekly caps), never your Shopify store.
3. Provisioning happens automatically on first launch of the embedded admin. Behind the scenes, KaireonAI creates a dedicated tenant, four storefront channels (shopify_product_page, shopify_cart, shopify_home, shopify_thank_you), the outcome types the app records (impression, click, add to cart, purchase, dismiss, refund), a default frequency-cap contact policy (max 3 offers/customer/day), and a bandit-scoring decision flow (shopify-nba-flow) that’s published and active immediately — there is no separate “publish your flow” step for the Shopify surface.
4. Import your catalog. Open the embedded admin’s Settings tab and click Run import now. New products are created as KaireonAI offers in draft status so you can review them before they go live on any storefront surface (see Curation and defaults below). Each imported offer also gets a creative for every surface — this is what actually lets it render as a card once you activate it; an offer with no creative for a surface can never appear there.
5. Curate and activate offers. In the Offers tab, activate the offers you want recommended, set an optional per-offer weekly cap, and choose which of the four surfaces each offer appears on. The surfaces you check control which storefront channels have an active creative for that offer; the weekly cap becomes a real per-offer frequency policy the decisioning engine enforces.
6. Add the storefront blocks in your theme editor (Online Store → Themes → Customize):
   • Product page — add the “Personalized offer” block to your product template.
   • Cart page — add the “Personalized offer” block to your cart template.
   • Home / collection page — add the “Personalized offer” block to your home page or a collection template.
   Each block is a self-contained app block (no configuration needed) that fetches a recommendation on page load and renders it once the card resolves — nothing renders (and no error is shown) if there’s no eligible offer for that visitor.
7. Confirm the Thank You page and checkout pixel are active. These are checkout/post-purchase extensions configured separately from theme blocks — your KaireonAI contact or the person who ran shopify app deploy confirms these are enabled for your store’s checkout.

​

Curation and defaults

• Newly imported or newly synced products default to draft — nothing appears on your storefront until you activate an offer.
• Every imported offer gets one creative per surface, all active by default, so a freshly-activated offer is immediately eligible on all four surfaces. Provisioning also happens for shops installed before this behavior existed — the first embedded-admin launch backfills creatives for your already-imported catalog.
• Surfaces are a real on/off switch. Un-checking a surface for an offer flips that surface’s creative to inactive (it’s never deleted, so re-checking it is instant); the offer then stops appearing there. An offer with every surface un-checked won’t render anywhere, even while active.
• The weekly cap is enforced, not cosmetic. Setting a per-offer weekly cap creates a frequency policy that limits how many times that offer can be shown to a given customer per week; clearing it to 0 removes the cap.
• There is no discount field. The app has read-only access to your catalog and holds no discount-writing scope, so it can’t apply a discount at checkout — a display-only percentage that never reached the cart would mislead shoppers, so it isn’t offered. Run discounts through Shopify’s own Discounts, and the imported offer’s price stays in sync.
• The “Automatically create newly-synced products as drafts” toggle (Settings tab) is persisted per tenant, but as of this writing it is not yet consumed anywhere — every import, regardless of this toggle’s value, currently creates new offers as drafts. Existing behavior (draft-first) matches what the toggle implies when left on (its default), so nothing is silently different today; a future release will make this toggle actually gate the behavior when turned off.
• Editing a product’s price, image, or category directly in Shopify re-syncs to the matching KaireonAI offer automatically — unless you’ve edited that field inside KaireonAI’s Offers tab, in which case your edit wins and future Shopify syncs stop overwriting that specific field.

​

How offers are ranked

Every Shopify tenant gets one auto-provisioned decision flow using a multi-armed bandit (Thompson sampling) scorer. The bandit starts with no historical data and learns from real storefront engagement (impressions, clicks, add-to-carts, purchases) over time — there is no manual weight-tuning step required to get started, and no separate “training” phase.

​

Storefront placements

​

How attribution works

KaireonAI tracks three tiers of signal for every recommended offer, from lightest-weight to authoritative:

1. Impressions, clicks, and add-to-carts are recorded the instant they happen, straight from the storefront block (via Shopify’s App Proxy) — these drive the bandit’s learning in near real time.
2. A checkout web pixel fires a lightweight corroboration event when checkout starts and completes. This never carries revenue on its own (it always records $0) — it exists purely to give the model an early signal before the authoritative order data has arrived.
3. The orders/create webhook is the authoritative revenue signal. When a customer completes an order containing an item that was added to cart via a KaireonAI offer, the webhook reads the order’s real line-item price, quantity, and any line-level discount, and records a “purchase” outcome with that exact revenue — this is what drives revenue reporting in the Performance tab and what the bandit learns from as a true positive/negative signal.

​

Refunds

A refunds/create webhook records a matching negative outcome (a “refund”) with the refunded amount, netting the original purchase’s revenue back out of your reporting and correcting the model’s learning signal. A refund on an item KaireonAI never recorded a purchase for (e.g., it predates the app, or the original webhook delivery was missed) has nothing to net against and is logged for the reconciliation sweep to catch instead.

​

Reconciliation

Webhooks are fast but best-effort — an occasional missed delivery is expected in any webhook-based integration. Every 6 hours, KaireonAI runs a reconciliation sweep per installed store that:

• Re-derives any purchase or refund outcome that a missed or failed webhook never recorded, from Shopify’s own order history.
• Catches any product created directly in Shopify that never triggered an import (there is no live products/create webhook — new products are picked up by this sweep, or by manually re-running the Settings tab’s import).

This means a brief webhook outage never permanently loses revenue attribution or a new product — it’s caught within a few hours at most.

​

Performance reporting

The embedded admin’s Performance tab shows, per offer, impressions, an “Engagements” count (clicks plus other positive interactions like add-to-cart, blended into one number), attributed revenue, and a conversion rate, over a 7/30/90-day window you choose.

​

Uninstalling

Uninstalling the app from your Shopify admin immediately stops all storefront personalization and revokes the credential KaireonAI’s edge service uses to call your tenant’s decisioning API — no further recommend/respond traffic is possible for your store after uninstall. Shopify’s GDPR compliance webhooks (customer data erasure/export requests, and a full-shop data erasure roughly 48 hours after uninstall) are honored automatically; no action is required on your part.

​

Privacy and data handling

• The app never receives or stores your customers’ names, emails, or addresses. Attribution is keyed on Shopify’s own numeric customer id (for logged-in customers) or an anonymous, cookie-based token (for guests) — neither is personally identifying on its own.
• Product catalog data synced into KaireonAI (name, price, image, category) is used only to power your own storefront’s recommendations.
• Customer data erasure and export requests initiated through Shopify (e.g., a customer requesting their data, or a merchant requesting erasure) are handled automatically via Shopify’s mandatory GDPR compliance webhooks.

​

Troubleshooting