Upgrading to V2

What changes when you move from CartPops V1 to V2, how to upgrade safely, and what to check afterwards.

CartPops V2 is a rebuild of the cart drawer, not a routine update. Your supported V1 settings carry over, but a few features are retired, some custom code stops working, and the minimum versions of PHP, WordPress and WooCommerce are higher.

How much work the upgrade takes depends on how much you customized. A store that uses the default drawer needs a few checks. A store with custom JavaScript, theme code that calls CartPops, or Pro automation rules needs more. Read this page before you update, then use the checklists.

Developers and agencies: see Upgrading to V2: for developers for the hook, JavaScript and template changes.

What V2 is

V2 builds the drawer from WordPress blocks and keeps it in sync with WooCommerce through the WooCommerce Store API. You get a Cart Drawer block and a Cart Launcher block for block themes. On classic themes, CartPops renders the drawer and launcher for you.

What this means for you:

• The drawer is the one cart experience. The beta popup, the beta bar and the V1 assistant are gone (see What looks or works differently).
• The drawer is new markup. Some V1 custom CSS and custom code will need changes.
• Product recommendations, the Pro shipping meter and the shipping calculator are rebuilt inside the drawer.

Requirements

V2 needs newer software than V1. Check all four before you update.

If your host does not meet the requirements

• PHP or WordPress too old. CartPops declares its PHP and WordPress minimums in the plugin header. WordPress uses them to refuse to install or activate the plugin, and normally shows the update as unavailable. The exact wording depends on your WordPress version.
• WooCommerce too old. CartPops also declares its WooCommerce minimum. WooCommerce reads it and can warn you about the incompatibility. Update WooCommerce first.
• MySQL or MariaDB too old. CartPops does not check the database version itself. Ask your host which version you run and whether they can move you to a supported one.

If your host cannot offer PHP 8.1 yet, stay on V1 until it can. Do not update CartPops until the requirements are met.

To find your PHP and database versions, go to Tools > Site Health > Info in WordPress and open the Server section.

Before you upgrade

Note your customizations

It also helps to take a few screenshots of the cart as it looks now, on desktop and on mobile, so you can compare.

Upgrade steps

CartPops Free

CartPops Pro

CartPops Pro is a separate plugin, not an add-on for Free. Its folder is cartpops-pro, and its updates and license come through Freemius.

What happens to your settings

CartPops migrates your settings for you. You do not need to export or re-enter them.

• It happens in place. The first time WordPress loads after the update, CartPops reads your V1 settings and writes them in the V2 format.
• Your V1 settings are kept. CartPops does not delete or change the V1 options. Before it migrates anything, it saves a read-only snapshot of them in your database.
• It is safe to run again. If the migration is interrupted or fails, it retries on the next load and ends with the same result. In general, a V2 value you have already saved is not overwritten.
• It does not guess. If a V1 value is malformed or cannot be converted safely, CartPops uses the V2 default for that setting, keeps the original, and shows a warning notice that names the setting. See Settings that did not carry over.
• It does not stop your store. Since 2.0.3, only custom JavaScript asks for your review before the migration finishes. CartPops Pro can also wait until your license is active on the site. Everything else completes and is reported as a warning.
• Licensing is kept. CartPops does not rewrite your Freemius license records.

Carried over: your drawer, design, launcher, recommendation and Pro shipping meter settings, the secondary drawer button (Pro), your custom CSS, and the V1 Force refresh on page load option (now Advanced > General > Performance > Refresh cart data on page load).

Kept in your database but not used by V2:

• Custom JavaScript. Stored untouched and never run.
• Automation and upsell rules (Pro).
• A few V1-only settings: popup and slider colors, the support chat toggle, and the old Continue shopping text (Popup) and View details text overrides.

Settings that did not carry over

If some V1 settings could not be carried over, WordPress admin shows:

CartPops updated your settings from version 1, but some could not be carried over exactly. Your original settings are kept.

(CartPops 2.0.0 to 2.0.2 worded it as “CartPops migrated legacy settings with compatibility warnings.”)

Click See which settings under the notice. It names each setting by the screen and label you knew in version 1, for example Settings → Cart Launcher: Hide on certain pages, grouped like this:

Your original V1 values stay in your database in every case. If something you rely on is missing and you cannot set it again, contact support.

When you have checked the list, click Hide this notice. It is hidden for you only, and it comes back if a later update changes the result.

What looks or works differently

The drawer is rebuilt

The drawer does the same job, but the layout, markup and some details are new. Your colors and settings carry over, so it should look familiar, but do not expect a pixel-for-pixel match. Review the Layout and Design tabs on the Drawer page after the upgrade, and see Drawer design.

Smaller changes you may notice:

• The recommendations strip scrolls natively instead of using a slider carousel.
• The Pro shipping meter is a horizontal bar only. The circular version is gone.
• The included-tax note under the total now appears only when both Show taxes and Show total are on. In V1 it depended on Show total alone.

The popup and the bar are gone

V1 had a beta popup and a beta bar, both Pro only. They were not selectable in the V1 1.5.45 settings screen. A store only used them if a saved value or custom code switched them on. In V2, a store that had either one set now gets the drawer instead.

The Smart Bar in the Pro drawer is a different feature and is still there.

The assistant is now an inline shipping calculator

The V1 Pro assistant was an overlay for choosing a shipping method. In V2 (Pro), shipping choice is a Calculate shipping section inside the drawer. Your V1 setting for it carries over as Enable shipping calculator. Links or buttons that opened the assistant with cpops-toggle-assistant no longer work. See Shipping calculator.

The shipping meter reads WooCommerce

In V2 the free shipping goal comes from WooCommerce: a Free shipping method with a minimum order amount in the shopper’s shipping zone. V1 let you type your own amount. V2 has no equivalent. A threshold you set in V1 can only raise the WooCommerce amount, never lower it, and it cannot create a free shipping goal when WooCommerce has none.

If you used your own amount in V1 and your zones have no Free shipping method with a minimum, the free shipping part of the meter will not show. Reward tiers still work. To bring it back, add a Free shipping method with a minimum amount to the zone in WooCommerce. See Free shipping progress bar.

Launchers and shortcodes

• The floating launcher is still there, with new markup.
• [cartpops_cart_launcher] still works. [cartpops_launcher] is the new name for the same shortcode.
• The shortcode icon option now accepts cart, bag and basket. The V1 cpops-icon- names map to the nearest of those. A custom icon name now shows the default cart icon.
• A classic menu item with the class cpops-cart-menu-item still becomes a launcher. It works in classic menus only, not in the Navigation block.

See Cart launcher and Shortcodes.

The cpops-toggle-drawer class is deprecated

In V1, adding the class cpops-toggle-drawer to any button, link or menu item made it open the drawer. V2 still does this, but it is deprecated and will stop working in a future version.

To open the drawer from your own button, use a CartPops launcher, or ask a developer to use the cartpops:open event described in the developer guide.

The WooCommerce View cart link that appears after an add on a shop page used to open the drawer. It now goes to the cart page.

Add to cart on product pages (classic themes)

V1 took over the add to cart form on single product pages. It added the product in the background and opened the drawer. V2 does this too, with a setting that is on by default: WooCommerce > CartPops > Advanced > General > Add to cart on product pages without reloading.

With it on, the shopper stays on the product page and the drawer opens if Open drawer on is set to Add to cart. WooCommerce’s own messages, such as “Please choose product options”, appear at the top of the product page as usual. The page still reloads the normal WooCommerce way for:

• products with a file upload field
• external/affiliate and grouped products
• stores that redirect to the cart after adding (WooCommerce > Settings > Products > Redirect to the cart page after successful addition)
• an add that fails to reach your store in the background

If your theme or another plugin already adds from the product page without reloading, CartPops leaves it to them. Turn the setting off if you prefer the page to reload.

Add to cart buttons on shop and category pages still open the drawer when WooCommerce adds in the background (WooCommerce > Settings > Products > Enable AJAX add to cart buttons on archives). Add to cart buttons in WooCommerce blocks are covered too.

If the drawer does not open from your product page, see The drawer does not open.

Custom JavaScript does not run

V1 had a Custom Javascript field under Custom code. V2 stores what you saved but never runs it. This is deliberate.

If your site had custom JavaScript, CartPops pauses after the update and shows a Review your old custom JavaScript notice to site administrators. Other users see that CartPops is waiting for a site administrator.

1. Click Show your saved custom JavaScript to see the exact code, and copy it somewhere safe.
2. Tick I understand this custom JavaScript will not run in CartPops 2.
3. Click Confirm and finish the update. CartPops finishes the update and starts working.

The code stays in your database, but the notice does not show it again. (In CartPops 2.0.0 to 2.0.2 the notice was called Review legacy JavaScript, and the button Acknowledge and retry migration.)

Your options for the code are to move it into your theme or a snippets plugin and update it for V2 (a developer can use the developer guide), or to drop it.

Custom CSS carries over, but check it

Your custom CSS is kept and loads after the CartPops styles. V2 keeps the cpops- and cartpops- class prefixes and many V1 class names. It also keeps the V1 color variables when you set them on :root. But the markup underneath changed, so rules that depend on V1 element IDs (such as #cpops-drawer-modal, #cartpops-drawer and #cpops-floating-cart) or on how deeply elements were nested may stop matching. Test your styling on desktop and mobile. You can edit it under WooCommerce > CartPops > Advanced > General > Custom CSS.

Automation and upsell rules are retired (Pro)

V1 Pro had automation rules (such as buy-one-get-one, coupon upsells and free upsells). V2 does not run them and does not convert them. Their data stays in your database untouched, and you will see a notice saying so.

If you want similar offers, set them up again with the V2 Pro features: Smart Bar spotlight discounts, shipping meter reward tiers (free gifts and discounts), the Bundle Builder and Smart add-ons. They are separate features with their own settings, not a one-to-one replacement. Check the Smart Bar, Bundle Builder and Smart add-ons guides.

Theme template overrides stop applying

If your theme had a cartpops folder that overrode CartPops templates, V2 ignores it. The drawer is built from blocks, so there is no template to override.

After upgrading: check these

Test as a guest in a private browser window, on desktop and on your phone.

• The drawer opens when you add a product on a shop page, on a product page and from a related product.
• On a classic theme, the add to cart button on a product page opens the drawer without reloading the page. If not, see above.
• The cart launcher shows the right count and opens the drawer. Check your header and menu launchers too.
• Quantity changes, remove and undo, a coupon, and the checkout button all work.
• Your custom CSS still looks right.
• Open your browser’s developer console and look for errors such as CartPops is not defined. They point to old custom code that needs updating.
• Pro: the shipping meter, calculator, recommendations and Smart Bar show as expected, and WooCommerce > CartPops shows no upgrade prompts.
• In WooCommerce > Settings > Products, Redirect to the cart page after successful addition is off and Enable AJAX add to cart buttons on archives is on. V1 warned you about these. V2 does not.
• You cleared every cache (page cache, CDN, and optimization plugin). See Caching.

Notices you may see

CartPops reports migration status in the WordPress admin, to users who can manage WooCommerce. Your original settings are preserved in every case.

For other errors, see CartPops stopped after upgrading, The drawer does not open and Caching.

Rolling back

CartPops V2 does not delete or change your V1 settings. It also keeps the snapshot it took before migrating. That is what makes a rollback possible, but a plugin rollback alone has limits.

The safest rollback restores your pre-upgrade database backup and your V1 plugin files together. This returns the site to exactly how it was.

A lighter rollback replaces the V2 plugin files with V1 and leaves the current database alone. V1 then reads its own untouched settings. Know what you give up:

• Changes you made in V2 do not carry back. V1 does not read the V2 settings.
• V1 rules are preserved in the database, but reinstalling V1 does not promise that they will run again.
• Clear your caches afterwards.

Do not edit or delete the CartPops migration records in the database, even to force a retry. If an upgrade is interrupted, leave your V1 settings alone, fix the problem the notice reports, and let CartPops retry.

Related

• Upgrading to V2: for developers
• Upgrading to V2: frequently asked questions
• CartPops stopped after upgrading
• The drawer does not open
• Caching
• Changelog