--- title: Upgrading to V2 description: What changes when you move from CartPops V1 to V2, how to upgrade safely, and what to check afterwards. sidebar: label: Upgrading to V2 order: 1 icon: rocket --- ![New in CartPops 2.0](/blume-assets/content/content/02-upgrading-to-v2/img/new-in-cartpops-2-0.png) 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](/upgrading-to-v2/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](#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. | Software | V2 minimum | | --- | --- | | PHP | 8.1 | | WordPress | 6.5 | | WooCommerce | 9.0 | | MySQL or MariaDB | MySQL 8.0, or MariaDB 10.11 | ### 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. :::warning[Do not force the plugin onto an older PHP version] CartPops does not include a fallback for PHP below 8.1. Do not copy the plugin files onto an older server to get around WordPress. Ask your host to move you to PHP 8.1 or newer first. ::: 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 1. **Back up** Back up your database and your plugin files. A database backup is what lets you fully roll back, so keep it until you are happy with V2. 2. **Use a staging copy if you can** Run the upgrade on a staging copy of your store first. Test the cart on staging the way a shopper would. 3. **Check your versions** Confirm PHP, WordPress, WooCommerce and your database meet the [requirements](#requirements). Update WordPress and WooCommerce first if they do not. 4. **Write down your customizations** Go through the list below. Anything you find may need attention after the upgrade. ### Note your customizations | If you have... | Why it matters | | --- | --- | | **Custom CSS** in the V1 **Custom code** settings | It carries over, but the drawer markup is new. Some selectors will stop matching. Copy the CSS somewhere safe first. | | **Custom JavaScript** in the V1 **Custom code** settings | V2 keeps it in your database but does not run it. Copy it somewhere safe. V2 has no screen that shows it. | | **Code in your theme or a snippets plugin** that uses CartPops hooks, `CartPops.drawer` or CartPops PHP functions | Most V1 hooks and the JavaScript object are gone or changed. Give the code to your developer, together with the [developer guide](/upgrading-to-v2/developers). | | **Menu items or buttons with the class `cpops-toggle-drawer`** | The class no longer opens the cart. See [below](#the-cpops-toggle-drawer-class-no-longer-opens-the-cart). | | **A `cartpops` folder in your theme** (template overrides) | V2 does not read it. The folder is harmless, and its changes no longer apply. | | **Automation or upsell rules** (Pro) | V1 rules do not run in V2. | | **A custom shipping meter threshold** (Pro) | The goal now comes from WooCommerce. See [the shipping meter](#the-shipping-meter-reads-woocommerce). | | **WPML translations** of the shipping meter text | Translations stored under the old names do not carry over. | | **A caching or optimization plugin** | Clear all caches after the upgrade. See [Caching](/troubleshooting/caching). | 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 1. **Back up** Make a fresh backup of your database and files, as above. 2. **Update the plugin** In WordPress, go to **Plugins** > **Installed Plugins** and click **Update now** under CartPops. Free updates come from WordPress.org. 3. **Load an admin page** CartPops migrates your settings the first time WordPress loads after the update. Open any wp-admin page and look for notices at the top. See [After upgrading](#after-upgrading-check-these) for what each notice means. 4. **Review your settings** Go to **WooCommerce** > **CartPops** and look through the **Drawer**, **Launcher** and **Advanced** pages. 5. **Clear caches and test** Clear your caches, then test as a guest in a private browser window. Use the checklist in [After upgrading](#after-upgrading-check-these). ### 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. 1. **Check your license** Make sure your license is active for this site. Pro updates need an active license. 2. **Back up** Make a fresh backup of your database and files. 3. **Update the Pro plugin** Go to **Plugins** > **Installed Plugins** and click **Update now** under CartPops Pro. If you update from a ZIP file, upload the V2 Pro ZIP and choose to replace the current version, so WordPress does not install a second copy. 4. **Do not run Free and Pro together** If CartPops Free and CartPops Pro are both active, CartPops pauses itself and shows this notice: "CartPops detected both the Free and Pro editions as active. CartPops was paused; deactivate one edition and reload this page." Nothing is deleted. Deactivate one edition and reload. Keep Pro if you have a license. 5. **Load an admin page and review** Open any wp-admin page so the settings migration runs, then go to **WooCommerce** > **CartPops**. Check that the Pro tabs are available. If they show upgrade prompts instead, see [CartPops stopped after upgrading](/troubleshooting/stopped-after-upgrading). 6. **Clear caches and test** Clear your caches, then test as a guest in a private browser window. ## 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 leaves it out of V2, keeps the original, and shows a warning notice. - **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. ## 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](/guides/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](/guides/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](/guides/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](/guides/launcher) and [Shortcodes](/guides/shortcodes). ### The `cpops-toggle-drawer` class no longer opens the cart In V1, adding the class `cpops-toggle-drawer` to any button, link or menu item made it open the drawer. That no longer works. In V2 the class is only a styling hook on CartPops' own launcher. 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](/upgrading-to-v2/developers#open-the-drawer-from-a-custom-button). 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](/troubleshooting/drawer-not-opening). ### 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. Most V1 snippets called the `CartPops.drawer` object, which no longer exists, so they would only have raised errors. Your options are to move the code into your theme or a snippets plugin and update it for V2 (a developer can use the [developer guide](/upgrading-to-v2/developers#javascript-api)), 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](/guides/smart-bar), [Bundle Builder](/guides/bundle-builder) and [Smart add-ons](/guides/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](#add-to-cart-on-product-pages-classic-themes). - [ ] 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](/troubleshooting/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. | Notice | What it means and what to do | | --- | --- | | "CartPops preserved legacy automation rule data for recovery, but those rules are retired and do not run in V2." | Expected if you had V1 rules. Nothing is wrong. See [automation rules](#automation-and-upsell-rules-are-retired-pro). | | "CartPops migrated legacy settings with compatibility warnings. Original settings remain available for recovery." | The migration finished, but some values could not be converted safely and were left out. Review your settings. Contact support if something you rely on is missing. | | "CartPops could not complete its legacy settings migration. The original settings were preserved; review the migration status before retrying." | The migration did not finish. Reload an admin page so it can retry. If the notice stays, contact support and include the notice text. | | "CartPops migration requires compatibility review before it can finish. Original settings remain available for recovery; resolve the reported migration warnings, then retry the migration." | Contact support and include the notice text. Do not delete any CartPops data. | | "CartPops network migration paused at site N and will retry it without skipping later sites. Original settings were preserved." | Multisite only. The network admin sees this. It retries by itself. If it stays, contact support. | For other errors, see [CartPops stopped after upgrading](/troubleshooting/stopped-after-upgrading), [The drawer does not open](/troubleshooting/drawer-not-opening) and [Caching](/troubleshooting/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. 1. **Back up the current state** Back up the site as it is now, in case you want to try V2 again. 2. **Restore** Restore your pre-upgrade database backup and your V1 plugin files together. If you only need the lighter rollback, replace the plugin files with V1 instead. 3. **Clear caches and test** Clear all caches, then test the cart as a guest. 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. :::tip Keep a copy of your V1 plugin ZIP before you update. Then a rollback does not depend on finding the old version afterwards. ::: ## Related - [Upgrading to V2: for developers](/upgrading-to-v2/developers) - [Upgrading to V2: frequently asked questions](/upgrading-to-v2/faq) - [CartPops stopped after upgrading](/troubleshooting/stopped-after-upgrading) - [The drawer does not open](/troubleshooting/drawer-not-opening) - [Caching](/troubleshooting/caching) - [Changelog](/changelog)