Use this article when the Smart Cart is on your storefront and it will not open, shows up alongside your theme's own cart, or leaves the page stuck after opening and closing the cart.
The Smart Cart does not replace your Shopify theme's cart. Rebuy never removes, disables, or overrides it, so your theme's cart is still on the page and still active until you shut it off yourself. Most Smart Cart problems on a storefront trace back to that job being unfinished rather than to a setting inside the cart.
Your theme's cart drawer still appears with the Smart Cart
Your theme's cart drawer, which merchants often call the native cart, still appears with the Smart Cart because nothing has hidden it yet. Rebuy never removes, disables, or overrides your theme's cart, so hiding it is a step you have to finish, and until you do, shoppers see both carts on every cart action.
Hiding it takes two steps, and both are required. CSS makes your theme's drawer invisible, and a script in Rebuy's hide callback closes it for real. CSS on its own leaves the drawer open behind the Smart Cart, which is what makes a page stop scrolling after a shopper closes the cart.
Start by collecting the selectors you need, in one pass. On your storefront, open your theme's cart drawer, right-click it, choose Inspect, and note:
The outermost element that wraps the drawer, often an ID such as
#CartDrawer.Its dark backdrop, if that is a sibling element rather than something inside the drawer.
Its close control, often a class such as
.drawer__close.
Step 1: Hide the drawer with CSS
Scope the CSS to the smart-cart--enabled class, which Rebuy adds to the <body> tag when the Smart Cart mounts, so your theme's drawer is hidden only on pages where the Smart Cart actually mounted and stays visible everywhere else.
In your Rebuy admin, open the cart, click the Global Settings gear, open Advanced, then paste into Custom CSS and click Save:
/* Hides the theme's own cart drawer only on pages where the Smart Cart mounted */
.smart-cart--enabled YOUR-DRAWER-SELECTOR { display: none; }
/* Add this only if your theme's dark backdrop is a separate element */
.smart-cart--enabled YOUR-OVERLAY-SELECTOR {
display: none !important;
}
Keep the space between .smart-cart--enabled and your own selector, and include !important, since a theme's own styling for its drawer often outranks the CSS you add here. A backdrop that sits outside the drawer needs its own selector, otherwise the drawer disappears and the page stays dimmed.
Note: smart-cart--enabled is added once when the Smart Cart mounts and is never removed, not even by destroy(), so CSS scoped to it applies for the whole page life. It is not the class that tracks whether the cart is open; that one is rebuy-cart-visible, which Rebuy adds on open and removes on close. Scoping a hide to rebuy-cart-visible would show your theme's drawer again every time a shopper closes the Smart Cart.
Step 2: Close the drawer with the hide callback
Your theme's drawer is still open behind the Smart Cart after Step 1, because CSS hides an element without closing it. Clicking your theme's own close control whenever the Smart Cart closes is what actually shuts the drawer, and it is what keeps your theme from holding the page in a state it thinks is still open.
In your Rebuy admin, open the cart, click the Global Settings gear, open Advanced, then Event Callbacks. Paste this into the hide callback, replacing the selector with your own, and click Save:
/* Closes the theme's own cart drawer whenever the Smart Cart closes */
document.querySelector('YOUR-CLOSE-BUTTON-SELECTOR')?.click();
Reload your storefront, open and close the Smart Cart, and confirm that only the Smart Cart appeared and that the page still scrolls. If the page will not scroll, the section on a page that will not scroll after the Smart Cart closes covers what to add next.
If your theme's drawer still flashes into view briefly on a slow connection, that is Rebuy loading after your theme rather than a CSS problem. Load Rebuy Faster covers reducing that gap.
The page will not scroll after the Smart Cart closes
A page that will not scroll after the Smart Cart closes is almost always your theme's own scroll lock still in effect, not Rebuy's.
Rebuy's scroll lock is a single CSS declaration, overflow: hidden !important, that applies through the rebuy-cart-visible class on the <body> tag. Rebuy adds that class when the cart opens and removes it when the cart closes, and the removal happens whether or not Rebuy thinks the cart was visible, so Rebuy's lock always releases. Rebuy never writes an inline style, never locks the <html> element, and never uses position: fixed for this.
To confirm which lock you are looking at, open the browser inspector on <body> while the page is stuck. If rebuy-cart-visible is gone from the class list and the page still will not scroll, the lock belongs to your theme.
Your theme holds that lock because its drawer is still open as far as your theme is concerned. If you have not yet put the close script in Rebuy's hide callback, that is the first fix, and the section on your theme's cart drawer still appearing with the Smart Cart covers it.
If the close script is already in the hide callback and the page still will not scroll, remove your theme's lock yourself in the same callback:
On your storefront, open your theme's cart drawer and look at the
<body>and<html>tags in the inspector. Note any class your theme added, such asno-scroll,overflow-hidden, orjs-drawer-open, and note whether either tag picked up an inlineoverflow: hiddenstyle.Add these lines to the hide callback underneath the close script, replacing the class name with the one you found. Common example below:
/* Releases the theme's own scroll lock, for a theme that leaves it applied after its drawer closes */
document.body.classList.remove('YOUR-SCROLL-LOCK-CLASS');
document.documentElement.classList.remove('YOUR-SCROLL-LOCK-CLASS');
document.body.style.overflow = '';
document.documentElement.style.overflow = '';
Note: If the page locks when the Smart Cart opens rather than when it closes, put the same code in the show callback, wrapped in setTimeout(() => { ... }, 200) so your theme's own open animation finishes before the code interrupts it.
The Smart Cart does not open when a shopper clicks the cart icon
When a click on the cart icon does nothing, or takes the shopper to your /cart page, the cause is almost always one of the following. Work down the list in order, since each check rules out the causes before it.
Rebuy is not on the page. Confirm the Rebuy Connector app embed is enabled on your published theme, as described in Smart Cart: Set Up and Publish Your Cart. With debug mode on, an absence of any
[Rebuy]message in the console points here.No Smart Cart is enabled on the store. Type
Rebuy.SmartCartin the console. If it comes backundefined, Rebuy loaded but no Smart Cart is published, so cart icon clicks fall through to/cart.The Smart Cart loaded but decided not to render on this page. The Smart Cart does not render on the
/cartpage, and it does not render on Shopify's or Recharge's checkout. On a page where it decided not to render, Rebuy releases the cart icon so clicks go to/cartas normal.Your theme's cart icon is not one of the elements Rebuy binds. Rebuy binds
[data-cart-open]elements, anchors whosehrefends in or contains/cart, and forms whoseactioncontains/cart. An icon that is a<button>with a JavaScript handler and no/cartanchor is not bound, and nothing happens when it is clicked. The fix is in the section on binding your theme's cart icon.The cart icon was added to the page after Rebuy finished loading. Rebuy binds the elements that exist when it initializes and does not watch for new ones, so an icon injected later by a sticky header, a section re-render, or a page-builder block never gets bound.
The shopper clicked before the Smart Cart was ready. The click appears to do nothing and then the cart opens by itself a moment later. Rebuy holds the click and opens the cart once it is ready, so this is a delay rather than a failure.
Something failed to download. With debug mode on, the console reports a chunk, template, or stylesheet failure. A failed stylesheet has its own signature, where the cart mounts but appears unstyled and does not slide in.
Bind your theme's cart icon to the Smart Cart yourself
When your theme's cart icon is not an element Rebuy binds automatically, you can bind it yourself with a short script in Rebuy's ready callback.
On your storefront, right-click the cart icon and choose Inspect.
Find a selector that matches the clickable element, such as
.header__icon--cart.In your Rebuy admin, open the cart, click the Global Settings gear in the editor sidebar, open Advanced, then Event Callbacks.
Paste this into the ready callback, replacing the selector with your own:
/* Opens the Smart Cart when the theme's own cart icon is clicked */
document.querySelector('.cart-icon')?.addEventListener('click', () => {
Rebuy.SmartCart.show();
});
If your cart icon is not in the page yet when Rebuy finishes loading, which is what happens with an icon a sticky header or a page-builder block adds later, wrap the same code in a delay so it runs after the icon exists:
/* Opens the Smart Cart when the theme's own cart icon is clicked */
setTimeout(() => {
document.querySelector('.cart-icon')?.addEventListener('click', () => {
Rebuy.SmartCart.show();
});
}, 800);
Add to cart on a product page does not open the Smart Cart
When add to cart does not open the Smart Cart, the Smart Cart usually never learned that the cart changed, because the Smart Cart mirrors the Shopify cart rather than owning the add-to-cart button on your product page.
Check in this order:
Does the page navigate? If adding a product takes the shopper to
/cart, set your Shopify theme's cart Type to Drawer as described in Smart Cart: Set Up and Publish Your Cart, since the Smart Cart does not render on/cart. If your theme offers no cart Type setting, or shoppers still land on/cartafter you set it to Drawer, the navigation is built into your theme. Your Shopify theme developer can remove that navigation, or you can switch to a theme that does not have it.Is the add a full page form post? Rebuy detects a cart change by watching the network requests your theme makes. A theme that submits the product form as a full page load rather than in the background gives Rebuy nothing to watch, and the cart is only correct after the reload.
Is the add-to-cart button customized? A heavily customized button often stops firing the request Rebuy watches for. Compare against your theme's default product form to confirm.
Is a page builder involved? A landing page built in a page-builder app frequently ships its own add-to-cart implementation that neither your theme's cart nor Rebuy can see.
If your theme's add works but the Smart Cart does not react, you can try forcing it from the ready callback by listening for clicks on the theme's own button and refreshing the cart:
/* Refreshes the Smart Cart and opens it after the theme's own add-to-cart button is clicked */
document.querySelector('YOUR-ADD-TO-CART-SELECTOR')?.addEventListener('click', () => {
setTimeout(() => {
Rebuy.Cart.fetchCart();
Rebuy.SmartCart.show();
}, 500);
});
Your theme's cart count or subtotal will not update
Rebuy writes the Smart Cart's item count and subtotal into your theme's own header elements, and it finds those elements using the selectors under Theme Selectors. When your theme's header number disagrees with what the Smart Cart shows, one of those selectors is not matching the element you expect it to.
Those settings live in Global Settings, then Advanced, then Theme Selectors. Item Count defaults to .cart-count and Cart Subtotal defaults to .cart-subtotal, which are the class names most Shopify themes use, so this works on most stores with no change from you. Rebuy's own guidance on these fields names a custom theme as the case that needs them updated.
Leave them as they are unless your theme's header number is actually wrong. Changing a selector that is already matching is how a header that was updating correctly stops.
The Smart Cart opens empty when Shopify says there are items in the cart
A Smart Cart that opens with no line items while Shopify's cart has items means the cart mounted and then rendered nothing, rather than failing to load at all.
Check these in order:
Product tags that hide line items. A product tagged
smart-cart-hiddenis removed from the rendered list on purpose. See Smart Cart Tags.A custom template. If the cart or the Cart Items component is using a custom template, switch it back to the default template and reload. If the line items appear, the template is where to look.
Stock on the products inside a Shopify bundle product. When the cart contains a bundle, confirm every product inside it is in stock before looking further.
Console errors. With debug mode on, reload and open the cart. An error thrown during render appears in the console with the
[Rebuy]prefix.
A third-party widget disappears while the Smart Cart is open
A third-party widget that disappears while the Smart Cart is open is being hidden on purpose, so that it does not sit on top of the cart, and it comes back as soon as the cart closes.
The widgets Rebuy hides include the accessibility toolbar trigger, Zendesk's launcher, Smile's UI containers, Gorgias's web messenger container, and a generic chat widget container. Rebuy also lowers Klaviyo's customer hub modal so it stops covering the cart. If one of your widgets needs to stay visible over the cart, that is a CSS override in Global Settings, then Advanced, then Custom CSS.
Custom code that calls the Smart Cart fails or breaks the cart
A script that calls the Smart Cart fails when it uses a method name the Smart Cart does not have. JavaScript throws on that call and abandons everything written after it, so one wrong name is enough to stop the whole script. In an event callback that takes the cart down with it, because your code runs inside the cart's own startup and open sequence.
document.querySelector fails the same way. When it matches nothing it returns nothing rather than an element, and calling .click() or .addEventListener() on nothing throws.
Note: Code you paste into an event callback runs inside a function Rebuy builds at cart lifecycle time, so a mistake in a callback shows up while the cart is initializing or opening rather than when you save it. If the cart stops working right after you edit a callback, empty that callback, save, and reload before looking anywhere else.
Methods you can call from custom code
The table below lists the Smart Cart methods Rebuy supports in your own scripts and what each one does, including how it behaves when the cart is not ready yet. Rebuy.SmartCart carries hundreds of other functions that the cart's own templates call, and Rebuy does not support calling those from custom code. Rebuy's Smart Cart developer reference is the full list of methods and events, with their payloads.
Method | What it does |
| Opens the cart. If the cart is not ready yet, Rebuy holds the call and opens the cart as soon as it is |
| Closes the cart. If the cart is not ready yet, the call does nothing and is not held |
| Initializes the cart. Rebuy already calls this during page load, so your own code rarely needs it |
| Tears the mounted cart down. It leaves the |
| Prints the cart's internal state to the browser console. It refuses unless debug mode is on |
Some method names people expect are not there, on the current cart or on Legacy, so a script calling one of them has been failing since the first time it ran rather than breaking recently. The table below pairs each of those names with what does the same job.
Name that does not exist | What to call instead |
|
|
|
|
| Read |
|
|
Listen for cart and Smart Cart events instead of calling methods on a timer
Rebuy dispatches DOM events on document as the cart changes, so code that has to react to a cart change should listen for an event rather than poll. Events are also how a theme developer hooks into the Smart Cart from theme code, instead of pasting into an Event Callback box in the Rebuy admin.
rebuy:cart.change fires whenever the Shopify cart changes, whichever side made the change:
/* Runs every time the cart changes, whether Rebuy or your theme made the change */
document.addEventListener('rebuy:cart.change', () => {
/* your code here. Read Rebuy.Cart.cart for the current cart */
});
Reading Rebuy.Cart.cart inside the listener is what Rebuy's own widgets do on this event, rather than reading the event payload.
Rebuy also dispatches cart events named rebuy:cart.add, rebuy:cart.init, rebuy:cart.ready, and rebuy:cart.enriched, and Smart Cart events of its own including rebuy:smartcart.show, rebuy:smartcart.hide, rebuy:smartcart.ready, and events for a line item being increased, decreased, or removed. rebuy:smartcart.show and rebuy:smartcart.hide do the same job as the show and hide Event Callbacks, for a developer working in theme code rather than in the Rebuy admin. Rebuy's Smart Cart developer reference lists every event name and what each one carries.
Scripts written for a Legacy Smart Cart
A script that was correct against a Legacy Smart Cart can fail on the latest Smart Cart version, because some method names changed and some were dropped entirely. The table below pairs the Legacy names that turn up most often in merchant scripts with what to call instead.
Legacy method | What to call on the latest Smart Cart version |
|
|
|
|
|
|
| Nothing replaces it |
| Nothing replaces it |
| Nothing replaces them |
Do not use the split-testing snippet from older documentation
Older documentation for split testing the Smart Cart shows a snippet that sets SmartCart.settings.preview_mode = false and then calls init(). Do not run it. On a store with a live Smart Cart it tears the cart down until the page is reloaded, and on a Legacy store in preview mode it throws.
Smart Cart A/B testing is a built-in feature now. See How to Split Test the Rebuy Smart Cart.
Turn on Rebuy's debug mode
Debug mode makes Rebuy print what it is doing to the browser console, and every message it prints is prefixed with [Rebuy]. Nothing about debug mode is visible to shoppers.
Debug mode reports on Rebuy's own behavior and nothing else. It tells you whether Rebuy loaded, whether the Smart Cart decided to render on the page it is on, whether a shopper's click arrived before the cart was ready, and what failed while the cart was initializing or rendering. It reports nothing about your theme's cart, and nothing about which of your theme's elements Rebuy bound, so a theme drawer that still appears, a page that will not scroll, and a cart icon that does nothing are diagnosed in the browser element inspector rather than in the console.
Use whichever activation suits what you are doing:
Add
?debug=trueto the end of any storefront URL. A bare?debugwith no value does nothing, so include true.Run
window.Rebuy.debug = truein the browser console. This lasts until the page reloads.Set the browser localStorage key
_rebuy-debugto the booleantrue. This survives reloads and page changes, which makes it the right choice for a multi-page reproduction.
With debug mode on, Rebuy.SmartCart.printLogData() prints a grouped snapshot of the Smart Cart's internal state to the console. That snapshot includes the full Tiered Progress Bar subtotal calculation with every term shown, which is the fastest way to find out why a progress bar thinks a cart is worth more or less than the shopper does. If you run it with debug mode off, it prints Debug mode must be enabled to view Smart Cart log data. and stops.
Why does the Smart Cart not open on the Shopify cart page?
The Smart Cart does not open on Shopify's cart page, /cart, because Shopify controls the cart on that page, so a shopper who lands there sees your theme's cart instead. The Smart Cart works best as your shoppers' only cart, all the way from adding a product to checking out, since it is where Rebuy's cart features such as the Tiered Progress Bar and cart upsells run. To keep shoppers in the Smart Cart, turn Use Cart Page off in Global Settings. A shopper who tries to visit /cart is then sent to your home page with the Smart Cart already open.
Use Cart Page appears in Global Settings only after you turn off the View Cart Button in the Smart Cart's Checkout Area. While the View Cart Button is on, shoppers can still reach /cart however Use Cart Page is set.
Why don't the Tiered Progress Bar, cart upsells, and free gifts work on the Shopify cart page?
The Tiered Progress Bar, cart upsells, and the other components you added to your Smart Cart do not appear on Shopify's cart page, /cart, because the Smart Cart does not render there. A shopper on that page sees your Shopify theme's cart instead, and the following also behave differently there:
The Tiered Progress Bar does not re-evaluate its tiers as the shopper changes quantities.
A free gift added by a Gift With Purchase widget is not removed when the shopper removes the product that qualified them for it.
To keep these features working all the way to checkout, keep shoppers in the Smart Cart by turning Use Cart Page off in Global Settings. A shopper who tries to visit /cart is then sent to your home page with the Smart Cart already open. Use Cart Page appears only after you turn off the View Cart Button in the Smart Cart's Checkout Area.
Why does my theme's native cart sometimes open instead of the Smart Cart?
Your theme's native cart can open instead of the Smart Cart when the cart icon is clicked while your store's page is still loading. Your Shopify theme, your other apps, and Rebuy all load as the page loads, and your theme's cart icon works from the moment your theme appears. The Smart Cart takes over the cart icon as soon as it is ready on the page, so a click in the first moment of a page load can still reach your native cart.
Keep the following in mind when you see this:
When you test your Smart Cart, let the page finish loading before you click the cart icon. Refreshing the page and clicking straight away tests how fast the page loads, not how the Smart Cart works.
Shoppers on a slower connection take longer to load every page, so that first moment lasts a little longer for them.
Other apps and scripts on your store load at the same time as Rebuy, and a store running many of them takes longer to finish loading.
Your native cart works as a safety net. If the Smart Cart cannot load for any reason, your native cart still lets shoppers add products and check out.
To have the Smart Cart ready as early as possible, load Rebuy through the Rebuy Connector app embed, which starts loading Rebuy at the top of every page. Load Rebuy Faster has the setup steps.
Why doesn't the Smart Cart update when I click Add to Cart on a product page until I refresh?
The Smart Cart only shows a product from a product page's Add to Cart button after a refresh when that button adds the product differently from Shopify's standard add-to-cart request. The Smart Cart updates the moment your product page's Add to Cart button sends that standard request, such as /cart/add.js, in the background. A product added another way still reaches your Shopify cart, and the Smart Cart shows it the next time the page loads.
The Add to Cart button usually adds the product a different way for one of these reasons:
Your product page's Add to Cart button was customized and no longer sends Shopify's standard add-to-cart request.
The page was built in a page-builder app that uses its own add-to-cart code instead of your theme's product form.
Each of these is fixed in your theme or page-builder code, which Rebuy Support does not write or troubleshoot. Your own developer can restore the standard request, or add a script to the Smart Cart's ready callback that refreshes the Smart Cart after your theme's button is clicked. That script is in the section on add to cart on a product page not opening the Smart Cart.
Why does add to cart on a page-builder landing page not open the Smart Cart?
Add to cart on a landing page built with a page builder app, such as GemPages, PageFly, or Shogun, can fail to open the Smart Cart because the page builder's button uses its own add-to-cart code instead of your theme's product form. The Smart Cart opens when it detects Shopify's standard add-to-cart request, such as /cart/add.js. A page builder's button may add the product another way, or send the shopper to your /cart page, where the Smart Cart does not appear.
To confirm the page builder is the cause, add the same product from one of your regular product pages. If the Smart Cart opens there but not on the landing page, the landing page's add-to-cart button is the cause, not a Rebuy setting.
To fix it, ask the page builder's support how to make its add-to-cart button send Shopify's standard add-to-cart request, or build that section of the landing page with your theme's own product form. Rebuy Support does not write or troubleshoot page builder code. Your own developer can also add a script to the Smart Cart's ready callback that refreshes and opens the Smart Cart after the page builder's button is clicked. That script is in the section on add to cart on a product page not opening the Smart Cart.
Why does the Buy Now button on my product page skip the Smart Cart?
The Buy Now button on your product page skips the Smart Cart because it is built to send the shopper straight to Shopify checkout with that product, without going through a cart. Many Shopify themes show this button next to Add to Cart, labeled Buy it now or as an express payment button such as Shop Pay. A shopper who uses it goes directly to checkout, so they do not see your Smart Cart, including its cart upsells and Tiered Progress Bar.
Keep the following in mind when your product pages show a Buy Now button:
A shopper who uses Buy Now and then leaves checkout through its cart link is taken to your
/cartpage. With Use Cart Page turned off in your Smart Cart's Global Settings, that visit sends them to your home page with the Smart Cart open, which can look like an unexpected redirect.A shopper who clicks Add to Cart instead sees the Smart Cart open with the product in it, along with any cart upsells or Tiered Progress Bar rewards you have set up, before they click through to checkout.
To keep every shopper on the path through the Smart Cart, turn off the Buy Now button in your Shopify theme editor. In many themes, it is the Show dynamic checkout buttons setting in the product page's Buy buttons block. With it off, Add to Cart is the way to buy from your product pages.