Last updated: 2026-05-29
Complete setup, admin reference, and troubleshooting for CartClimb. For a guided first-time install, start with the Installation guide.
CartClimb installs from the Shopify App Store, configures inside Shopify admin, and renders on your storefront automatically once a theme block is added. The full walk-through with plan selection lives in the Installation guide. This page is for reference and troubleshooting after install.
| Plan | Price | Free trial | What's included |
|---|---|---|---|
| Free | $0 / mo | — | Static promotional banner only. No progress bar. |
| Lite | $4.99 / mo | 7 days | Single-tier progress bar, all banner modes (static / marquee / rotating), countdown, scheduling. |
| Pro | $7.99 / mo | 7 days | Everything in Lite, plus: multi-tier cascade (up to 3 tiers), free-gift auto-add, geo-targeting + per-country currency, cart upsell, and Checkout Plus extensions. |
Manage your subscription in Apps → CartClimb → Billing. Upgrades take effect immediately; downgrades take effect at the end of the current billing cycle.
CartClimb's admin is a single-column page per feature with a sticky Live Preview pane on the right. The left nav inside the app has these top-level pages:
| Page | What you do here |
|---|---|
| Progress Bar | Enable/disable, choose display mode, configure tiers, customize colors and messages, set device + page targeting, set geo rules. |
| Promotional Banner | Enable/disable, pick a banner mode, write messages, configure scheduling and targeting. |
| Upsells | Pro. Create and manage Upsell Groups used by the cart upsell carousel. |
| Performance | Order-attributed metrics, storefront funnel counters, and a 12-month AOV trend. |
| Billing | View current plan, change plan, see trial / period status. |
| Help | Setup checklist, common questions, troubleshooting tools (including the theme-compatibility report for the gift-line auto-add). |
A consolidated Targeting tab inside each feature covers both device (mobile / desktop / tablet) and page (home / product / collection / cart / drawer) visibility rules.
The storefront block is called Shipping Progress Bar. Add it from Online Store → Themes → Customize → Add section → Apps in any template where you want the bar to render (Home, Product, Cart, the cart drawer, etc.). The block uses the body target so it appears as a top-level section. There is no theme-code editing required.
Each tier has a dollar threshold and a reward type. Configure up to three tiers on Pro; Lite supports one.
| Type | What happens |
|---|---|
| Free shipping | The bar messages free-shipping unlocked. Pair with a real Shopify shipping rate to actually waive shipping at checkout. |
| Percentage discount | The bar messages X% off unlocked. Pair with a Shopify automatic discount or a code you communicate. |
| Free gift | The bar messages a gift unlocked. Pro. CartClimb auto-adds the gift line to the cart when the threshold is crossed, and the bundled CartClimb Free Gift Discount Function (a Shopify Function shipped with the app) discounts the gift line to $0. |
| Custom | Display-only message. You're responsible for delivering whatever the message promises. |
Multi-Tier Stepped is no longer a separate mode. Existing configurations using it are migrated to Linear Classic on read. The renderer is kept as a safety net but no new config will route to it.
CartClimb counts only items that physically ship toward a free-shipping tier threshold. Gift cards, digital downloads, and gift wrap configured as non-shipping items don't inflate the bar past the threshold. This means the bar matches what Shopify's checkout will actually do — most stores' shipping rates are configured against the shippable subtotal too.
Toggle in Progress Bar → Advanced → Only count shippable items toward free-shipping reward. The setting is global per shop and applies only to free-shipping tiers; percent-off and free-gift tiers continue to use the full cart subtotal.
If you ship gift cards physically and want them to count, flip the toggle off.
The progress bar shows progress visually. The reward also needs to exist in Shopify, or the bar promises something checkout doesn't deliver.
Free shipping
Percentage off
Free gift (Pro)
Show different thresholds and currencies based on the shopper's country. Eight countries are pre-configured today: United States (USD), United Kingdom (GBP), Canada (CAD), Australia (AUD), Germany (EUR), France (EUR), Japan (JPY), India (INR).
Setup:
The default currency (set on the same page) covers all countries without an explicit rule. If a country has no rule and Shopify's currency for the shopper differs from your default, the bar falls back to your default.
A site-wide announcement banner that runs independently of the progress bar. Useful for sales, shipping notices, holiday hours, or any campaign you want visible above the fold.
Block name: Promotional Banner. Add the same way as the progress bar (Theme customizer → Add section → Apps → Promotional Banner).
| Mode | Plan | Behavior |
|---|---|---|
| Static | Free + Lite + Pro | Fixed message. |
| Marquee | Lite + Pro | Scrolling horizontal text. |
| Rotating | Lite + Pro | Cycles through multiple messages on a timer. |
Set a start time and end time so the banner auto-shows and auto-hides for a sale window. Set in Promotional Banner → Scheduling.
Same consolidated Targeting tab as the progress bar — pick devices (mobile / desktop / tablet) and pages (home / product / collection / cart / drawer / custom URL patterns). Geo-targeting follows the same country list as the progress bar when enabled.
A product-recommendation carousel that renders inside the cart drawer or on the cart page, designed to lift average order value after the shopper has already committed to buying something.
cart-drawer-recs).| Mode | What it does |
|---|---|
| Manual | You pick specific products / variants. Order is preserved. Out-of-stock items are filtered at render. |
| Automatic | CartClimb picks based on current cart contents (frequently bought together, complementary). Tier-aware on Pro — if a shopper is one item away from a reward, the carousel prioritizes items that close the gap. |
Block name: CartClimb Upsell. This is a section-target block — add it via Add block inside the section where you want it, not as a standalone top-level section. Set the Recommendation group key in the block settings to match the key you used in the admin.
The same block works in the cart drawer, the cart page, or — when placed on a product template — the product detail page. The same group can serve multiple placements; use different groups when you want different recommendations per surface.
Two checkout UI extensions are bundled with CartClimb. They render inside the one-page Shopify checkout, which Shopify gates to Plus merchants only.
| Extension | What it does |
|---|---|
| CartClimb Checkout Progress Bar | Renders the same progress bar inside checkout's order summary. |
| CartClimb Checkout Upsell | Shows recommended-product cards with one-click add inside checkout. |
Apps → CartClimb → Performance shows three independent sections. Their numbers won't agree with each other — that's by design.
What shoppers actually bought. Populated from the orders/paid webhook attribution.
| Card | Meaning |
|---|---|
| Orders (30d) | Total paid orders. |
| Average order value | Revenue ÷ orders. |
| Upsell revenue (30d) | Sum of order-line totals that came from upsell-tagged lines. |
| Free gifts given | Orders that included a CartClimb-tagged gift line at purchase. |
| Orders reaching a reward | Orders whose subtotal crossed at least one tier. |
| CartClimb-influenced orders | Orders touched by a gift, upsell, or tier crossing. |
Order-attributed metrics depend on Shopify Protected Customer Data access. If your shop hasn't been approved yet, the section shows an empty state — see Data & Privacy below.
What shoppers do on the storefront, regardless of whether they buy. Populated from the storefront widget via sendBeacon.
| Card | Meaning |
|---|---|
| Bar impressions | Page-loads where the progress bar rendered. |
| Carts that crossed a tier | Shopper unlocked a reward in-cart. Different from "Orders reaching a reward" — that's purchases, this is engagement. |
| Gifts auto-added | Free-gift lines added by the widget. Different from "Free gifts given" — that's purchased orders with gifts. The gap between the two is your gift-add → purchase conversion. |
| Upsell shown → added | Ratio of upsell impressions to upsell adds. Shows "—" until any upsell impressions accumulate. |
Pulled from Shopify's own analytics (ShopifyQL) — store-wide AOV by month, not CartClimb-attributed. Your install month is marked so you can read the table as before / after.
All numbers shown are CartClimb-attributed (last-click), not causal lift. A true revenue-lift claim still requires an A/B holdout — that's on the roadmap and intentionally not pre-baked. The dashboard's banner states this.
Do not test inside the Shopify theme customizer. Cart monitoring is disabled there — the bar will appear, but it won't update when you add items. Always test on your live store URL.
| Where | OK? |
|---|---|
https://your-store.myshopify.com | ✅ Test here |
https://your-storefront-domain.com (custom domain) | ✅ Test here |
https://admin.shopify.com/.../editor | ❌ Won't update |
Open the browser console (F12 → Console tab) and filter for [SPB] — this is CartClimb's log prefix. Useful messages include:
[SPB] sync no-op — subtotal … — the gift-sync ran but nothing needed to change.[SPB] adding gift … / removing gift … — the gift-sync added or removed the auto-gift line.[SPB] Error fetching cart: … — the storefront couldn't reach Shopify's /cart.js (usually a theme override or a network block).[SPB] Failed to fetch settings from API … — the storefront couldn't reach our settings endpoint. Most often a Cloudflare / firewall rule blocking the merchant's site from talking to cart-incentives.fly.dev.| Cause | Fix |
|---|---|
| Enable toggle is off in admin | Turn it on at the top of the Progress Bar page. |
| Theme block not added | Theme customizer → Add section → Apps → Shipping Progress Bar. |
| Device hidden by targeting | Targeting tab — confirm "Show on mobile / desktop / tablet" matches where you're testing. |
| Page hidden by targeting | Targeting tab — confirm the current page is allowed. |
| Free plan | The progress bar isn't included on the Free plan. Upgrade to Lite or Pro under Billing. |
| Cause | Fix |
|---|---|
| Testing inside the theme customizer | Open the live store URL (your-store.myshopify.com) in a regular tab. |
| Custom cart drawer override | Check the browser console for [SPB] errors. Some themes wrap the cart drawer in an unusual way — open Admin → Help to run the theme-compatibility report. |
| Network blocking | The merchant's site couldn't reach cart-incentives.fly.dev. Check for Cloudflare rules or a corporate proxy. |
| Cause | Fix |
|---|---|
| Settings not saved | Click Save in the admin panel. |
| Browser cache | Hard-refresh on the storefront (⌘/Ctrl + Shift + R). |
| Theme CSS override | Inspect the bar element in DevTools — if a theme rule has !important, you'll need a custom CSS selector or to contact support. |
This is exactly the case the shippable-only filter exists to prevent. Make sure Progress Bar → Advanced → Only count shippable items toward free-shipping reward is on (it's on by default for new and existing shops). If a gift card or digital line is in the cart, those won't count toward a free-shipping tier — and they shouldn't, because your Shopify shipping rule won't count them either.
| Cause | Fix |
|---|---|
| Plan isn't Pro | Free-gift auto-add is a Pro feature. |
| Discount function not activated | Discounts → activate CartClimb Free Gift. |
| Gift variant out of stock | The gift won't add if the variant has 0 inventory and "Don't sell when out of stock" is set on the product. |
| Theme override removes lines on render | Run the theme-compatibility report in Admin → Help. |
Express checkout buttons bypass the cart entirely, so the cart-side gift auto-add and the cart-side upsell don't run. The Checkout Progress Bar still renders inside the express order summary. The Checkout Upsell renders only on standard checkout — there is no upstream hook in express. This is a Shopify-platform constraint, not something we can fix with a setting; we're tracking it on the roadmap.
| Cause | Fix |
|---|---|
| Country has no rule | Add a rule for that country, or rely on the default currency. |
| Shopify Markets currency mismatch | Confirm your Shopify Markets configuration matches the country rule. |
| Testing through a VPN | Disable the VPN to confirm the issue isn't your test setup. |
CartClimb is built to read as little data as possible. The short version:
orders/paid webhook (requires Shopify Protected Customer Data access). We read the order id, totals, currency, and line-item properties — specifically our own _cartclimb_upsell and _cartclimb_gift_tier_id tags. We do not read customer name, email, phone, address, or IP.navigator.sendBeacon to our own endpoint. No customer identifier travels with these — just the event type and your shop domain.shop/redact, and on customers/redact, we delete settings, sessions, analytics records, order facts, daily metrics, and funnel counters. All three GDPR webhooks are honored.Full policy: Privacy.