The two ingredients#
Your catalog#
Your catalog is CartAmplify’s mirror of your storefront. Every product you sell, in every language you sell it.
What CartAmplify needs to know#
Every product has a few required fields — the minimum needed for it to appear in search and recommendations:
- A unique product ID (your SKU works)
- A language code (English, French, Spanish, etc.)
- Title
- A link back to the product page on your store
- Price + currency
- Availability (in stock, out of stock, preorder, backorder)
And a long list of valuable optional fields — the more you fill in, the better everything works:
- Description (helps search understand what the product is)
- Categories (a hierarchical path like
"Clothing > Men > Shirts"— multiple paths supported per product) - Brand, tags, sizes, materials, condition
- Images
- Custom attributes (color, fit, age range, anything that matters)
- Quantity in stock
- Original price (for ”% off” displays)
How it gets there#
For supported platforms, the plugin keeps your catalog in sync automatically. Add a product in Shopify; it appears in CartAmplify within minutes. Mark something out of stock; it stops appearing in results within minutes.
For custom storefronts, you send your catalog via the API. Two patterns:
- Bulk sync — send your full catalog in pages of up to 1,000 products. Used for the initial import and any scheduled full re-sync.
- Single-product updates — create, update, or delete one product at a time, in real time as your inventory changes.
Out-of-stock handling#
Set a product’s availability to OUT_OF_STOCK and CartAmplify hides it from search, browse, and recommendation results by default. This is what you want most of the time — shoppers shouldn’t see products they can’t buy.
You can flip this per widget if you have a “notify when back in stock” UX, or for editorial reasons. It’s a per-widget toggle in the dashboard, not a catalog setting.
How big can your catalog be?#
| Tier | Max products |
|---|---|
| Starter | 500 |
| Growth | 5,000 |
| Amplify | 50,000 |
| Enterprise | 50,000+ (contact us) |
If your store has more products than your plan allows, the excess are rejected during sync — you’ll see them in the dashboard’s sync log so you know what didn’t make it.
Shopper events#
While your catalog tells CartAmplify what you sell, events tell it what’s happening on your store. Each event is a single shopper action — viewing a product, adding to cart, searching for something, completing a purchase.
Why events matter#
Three things depend on events:
Analytics. Your dashboard charts — funnels, click-through rates, revenue attribution — are all computed from events. No events, no analytics.
Personalization. The smart, per-shopper version of search, browse, and recommendations needs behavioral data. Before events flow, results are based on the catalog and overall popularity. After about a week of normal traffic, personalization activates.
Discovery of catalog gaps. “Zero-result queries” — shoppers searching for things you don’t sell, or things named differently in your catalog — are a goldmine of merchandising decisions. Events surface them.
The seven event types#
| Event | When to fire | What it tells CartAmplify |
|---|---|---|
| Home page view | Visitor lands on the homepage | ”Someone arrived” — useful for personalized homepage shelves |
| Category page view | Visitor opens a category page | What categories matter to this shopper |
| Detail page view | Visitor opens a product page | The strongest interest signal |
| Add to cart | Item added to the cart | High-intent — shopper is considering buying |
| Cart page view | Visitor opens the cart | Context for cart-page recommendations |
| Purchase complete | Order finished | The ground truth — what people actually buy |
| Search | Shopper submits a search query | What people are looking for + which queries return nothing |
You don’t pick these manually if you’re on a platform plugin — the plugin fires the right events at the right moments. For custom storefronts, your developer wires each one into your frontend or backend.
Importing historical events#
If you have analytics history in Google Analytics, your warehouse, or your platform’s data export, you can bulk-import past events to fast-forward personalization. Up to 1,000 events per request, with relaxed timestamp rules so you can backfill years of history.
The benefit: instead of waiting a week for personalization to wake up, you can hit the threshold the day you connect, with personalization activating shortly after.
Connecting events across sessions#
Every event includes a visitorId — an anonymous identifier (typically stored in a cookie) that ties a shopper’s actions together across sessions. If a shopper logs in, you can optionally also send a userId. When both are sent, CartAmplify can unify anonymous and authenticated activity for the same person — so the same shopper on phone and laptop sees recommendations that reflect their full history.
Attribution — knowing which surface drove the sale#
Every search, browse, and recommendation response includes an “attribution token” — a small identifier the storefront passes through subsequent events. When the eventual purchase event includes that token, CartAmplify credits the original surface for the conversion.
This is how your dashboard can tell you revenue from search vs revenue from each recommendation widget. Without attribution tokens, conversions are unattributed and show up as “direct.”
Platform plugins thread attribution tokens automatically. For custom integrations, your developer handles this — see the API reference for the exact field.