Documentation

Everything you need to set up and get the most out of Smart Cart OS.

Setting up goals

In the Shopify Theme Editor, find the Smart Cart OS block. You'll see settings for Goal 1, Goal 2, and Goal 3. For each goal:

• Enable/Disable — toggle the goal on or off
• Label — what customers see (e.g. "Free Shipping")
• Threshold — the spend amount to unlock the reward (e.g. £25)
• Icon — choose from truck, gift, or tag icons

Goals are automatically sorted by threshold and chain together. When a customer hits Goal 1, the bar advances to Goal 2.

Recommendation modes

Automatic (default)

Uses a cascading priority system that requires zero setup:

• First checks for manual metafield overrides on the product
• Then looks for products in the same collection
• Then matches by product type or tags
• Falls back to Shopify's built-in Recommendations API

Shopify API only

Uses only Shopify's built-in product recommendation engine. Good if you want Shopify to handle all recommendation logic.

Manual overrides only

Reads from a product metafield called custom.smart_cart_recs. Set this to a comma-separated list of product handles to control exactly which products appear as cross-sells.

Fastest path suggestions

Smart Cart OS automatically calculates the cheapest product that will unlock the next reward. It shows a one-tap "Add" button so customers can reach their goal instantly. This feature can be toggled on or off in settings.

Variant selector

For products with multiple variants (e.g. sizes), Smart Cart OS shows a dropdown in the cross-sell carousel. Customers can pick their size (XS/S/M/L/XL) before adding to cart — no need to leave the cart drawer.

Customising the appearance

All visual settings are in the Theme Editor:

• Accent colour — used for progress bars and highlights
• Success colour — used for completed goals
• Border radius — control how rounded the elements look
• Headings and labels — customise the cross-sell heading, add-on heading, checkout button text
• Module toggles — turn individual features on or off (goals, fastest path, cross-sells, add-ons, discount field, trust badges)

Analytics & tracking

Smart Cart OS tracks the following events:

• cart_opened — every time the cart drawer opens
• sc_add_to_cart — items added via cross-sell, quick add-ons, or fastest path
• sc_remove_from_cart — items removed that were added via Smart Cart
• goal_completed — each goal unlocked (deduplicated)
• checkout_clicked — with full session summary

Debug mode

Open your browser console and run these commands:

SmartCartAnalytics.getSummary()    // Full session summary
SmartCartAnalytics.enableDebug()   // Turn on console logging
SmartCartAnalytics.getEventLog()   // Raw event array

External integration

Smart Cart OS fires a custom DOM event smartcart:event for every tracked action. You can capture this in Google Analytics 4, Klaviyo, or any other tool that listens for custom events.

Fail-safe architecture

Smart Cart OS is designed to never break your checkout:

• The checkout button is a plain <a href="/checkout"> link — it works even without JavaScript
• Every feature module is wrapped in its own try/catch block
• The entire init function is wrapped in a try/catch
• If anything fails, the cart still works normally

Need help?

Email us at support@peasoupdigital.com or visit the Support page.