Upgrading to V2: for developers

Every V1 hook, JavaScript method, shortcode, template, endpoint and CSS hook, what happened to it in V2, and how to migrate your code.

This page is for developers and agencies who wrote code against CartPops V1 (1.5.x). It lists what is kept, changed or removed in V2, and what to use instead. Store owners should start with Upgrading to V2.

V2 references: PHP actions, PHP filters, JavaScript, Store API and REST and CSS customization.

What changed in the architecture

V1 rendered the drawer from PHP templates, loaded cart changes through admin-ajax.php actions, swapped HTML fragments into the page by CSS selector, and exposed a jQuery-based window.CartPops object. V2 renders the drawer as a server-rendered block (cartpops/cart-drawer, plus cartpops/cart-launcher), updates it on the client with the WordPress Interactivity API (a store named cartpops), and reads and changes the cart through the WooCommerce Store API and the cartpops/v1 REST namespace. There are no V1 PHP templates to override, no HTML fragments to replace, and no window.CartPops. PHP hooks that fired while V1 built markup now fire once per server render of the drawer block. They do not run again when the browser updates items, coupons, recommendations, shipping or totals.

Start here: what is most likely to break

1. window.CartPops does not exist. Any code that touches it throws a ReferenceError.
2. cpops-toggle-drawer no longer opens the drawer. It is a styling class on CartPops’ own launcher only.
3. Custom JavaScript from V1 is never executed. It is quarantined in the database.
4. Per-item, totals and class filters are not applied. woocommerce_after_cart_item_name, the cartpops_cart_totals_*_html filters and the cartpops_*_classes filters do nothing.
5. Theme template overrides are ignored. {theme}/cartpops/... is no longer read.
6. CartPops sends the single product page form.cart in the background only when its setting is on. Add to cart on product pages without reloading (Advanced > General) is on by default. A submit handler of your own that calls event.preventDefault() keeps the form; CartPops then does nothing.
7. admin-ajax.php actions and HTML fragments are gone. Use the Store API and cartpops/v1.
8. fs_cartpops() can return null. Check before you call methods on it.

PHP actions

Drawer actions fire with no arguments, once per server render of the drawer block. A callback that prints markup owns its escaping, accessibility and balanced HTML. Native V2 sections are not callbacks on these actions. Priority cannot interleave your output with them, and remove_action() against a V1 native callback is now a no-op.

For the full position table, see PHP actions.

Removed actions

The actions below have no V2 equivalent. Popup, bar and assistant were Pro-only in V1, so Free sites never had them.

cartpops_popup_wrapper_start, cartpops_popup_wrapper_end
cartpops_recommendation_popup
cartpops_cart_trigger_contents, cartpops_last_cart_item
cartpops_free_shipping_meter_horizontal, cartpops_powered_by
cartpops_assistant_wrapper_start, cartpops_assistant_wrapper_end
cartpops_assistant_panel, cartpops_assistant_panel_top, cartpops_assistant_panel_bottom
cartpops_assistant_panel_wrapper_start, cartpops_assistant_panel_wrapper_end

cartpops_after_created_new_rule, cartpops_after_updated_rule
cartpops_before_rule_general_settings, cartpops_after_rule_general_settings
cartpops_before_rule_criteria_settings, cartpops_after_rule_criteria_settings
cartpops_before_rule_filters_settings, cartpops_after_rule_filters_settings
cartpops_before_rule_restrictions_settings, cartpops_after_rule_restrictions_settings
cartpops_before_rule_notices_settings, cartpops_after_rule_notices_settings
cartpops_rule_data_panels, cartpops_update_rule_order_count, cartpops_update_rule_user_usage_count

cartpops_admin_settings_menu_title, cartpops_admin_settings_page_title
cartpops_admin_settings_sanitize_option, cartpops_settings_fields
cartpops_settings_menu_items, cartpops_settings_tabs_array
cartpops_default_settings, cartpops_page_screen_ids, cartpops_plugin_issues_list
cartpops_before_shortcode_contents, cartpops_after_shortcodes_content

PHP filters

Kept or changed

Replaced

New in V2

Removed

cartpops_drawer_classes, cartpops_drawer_empty_cart_classes
cartpops_drawer_header_classes, cartpops_drawer_footer_classes
cartpops_drawer_coupon_form_classes, cartpops_drawer_cart_totals_classes
cartpops_drawer_recommendations_classes, cartpops_drawer_cart_item_classes
cartpops_single_line_item_classes, cartpops_powered_by_classes
cartpops_cart_launcher_classes, cartpops_floating_cart_launcher_classes
cartpops_drawer_shipping_meter_classes, cartpops_shipping_classes

cartpops_cart_totals_subtotal_html, cartpops_cart_totals_order_total_html
cartpops_cart_totals_vat_total_html, cartpops_cart_totals_discount_total_html
cartpops_cart_totals_shipping_html
cartpops_cart_item_price_display, cartpops_after_cart_item_name_price
cartpops_drawer_notice_html, cartpops_notices_html, cartpops_kses_notice_allowed_tags

cartpops_notification_remove_delay, cartpops_loading_state_delay
cartpops_generic_error_message
cartpops_cart_item_removed_title, cartpops_cart_item_removed_notice_type
cartpops_ajax_fragments, cartpops_available_cart_fragments
cartpops_bundled_items_data, cartpops_get_product
cartpops_template, cartpops_template_path

cartpops_alt_trigger_classes, cartpops_last_cart_item_classes
cartpops_popup_recommendations_classes
cartpops_assistant_content, cartpops_assistant_content_classes
out_of_stock_add_to_cart_text, out_of_stock_add_to_cart_url
cartpops_pagination_classes, cartpops_pagination_number
cartpops_get_dropdown_upsell_product_name, cartpops_show_dropdown_add_to_button
cartpops_upsell_product_add_to_cart_button_label
cartpops_upsell_product_dropdown_default_value_label
cartpops_upsell_product_heading_label

cartpops_add_custom_post_types, cartpops_add_custom_post_status
cartpops_rules_post_type_args, cartpops_master_log_post_type_args
cartpops_active_post_status_args, cartpops_inactive_post_status_args
cartpops_manual_post_status_args, cartpops_automatic_post_status_args
cartpops_rule_statuses, cartpops_master_log_statuses, cartpops_paid_order_statuses
cartpops_rule_data_tabs, cartpops_rule_translate_string

The documented V1 names cartpops_drawer_inside (it never fired in V1), cartpops_cart_totals_subtotal_total_html (a typo for the subtotal filter) and the callback names cartpops_checkout_url and cartpops_empty_cart_url in old docs were never real hooks.

WooCommerce hooks in the drawer

V1 re-fired many WooCommerce hooks while it built its own cart rows. V2 builds rows from WooCommerce’s cart data and Store API, so only these hooks still matter.

JavaScript API

V1 exposed window.CartPops with drawer, popup, bar and assistant objects. V2 has no global object. Classic scripts talk to the drawer through DOM events on document.

V2 browser events:

Things to know:

• The cartpops:open, cartpops:close and cartpops:toggle listeners are installed when the drawer’s script module loads. An event dispatched earlier, such as at DOMContentLoaded, is ignored. Dispatch from a user action, such as a click.
• V2 has no cartpops:ready, cartpops:opened or cartpops:closed event. To react to the drawer opening, you have no supported signal.
• CartPops still listens for WooCommerce’s jQuery added_to_cart event to open the drawer, but only if window.jQuery exists when its script module runs. A plugin that delays or defers jQuery can stop it from hearing classic AJAX adds.
• Adds that CartPops makes itself, such as recommendation or bundle adds, do not fire jQuery added_to_cart. Analytics or dataLayer code that listens for it will miss them.
• data-cpops-cart-open="false" on an add to cart button still stops that one add from opening the drawer.
• Quarantined V1 custom JavaScript is never executed. Move it into your theme or a plugin and rewrite it against the events above.

Shortcodes and menu items

Shortcode launchers take their colors from Launcher > Inline launcher appearance, not from attributes.

Templates and overrides

V1 let a theme override templates in {theme}/cartpops/{slug}.php. The assistant template loaded from {theme}/woocommerce/premium/assistant.php. V2 has no template loader and does not read either location. A copied V1 cartpops folder is dead code and does no harm.

The removed loader functions are cartpops_get_template(), cartpops_get_theme_template(), cartpops_get_plugin_template() and cartpops_template_path(), plus the cartpops_template and cartpops_template_path filters.

There is no supported way to replace the drawer’s markup. Use the action positions for static additions, cartpops_cart_item_data for row text, and CSS for appearance.

Global functions, constants and classes

cartpops_get_wc_cart_category_subtotal, cartpops_get_product_count_in_cart
cartpops_get_buy_product_count_in_cart, cartpops_get_coupon_upsell_product_count_in_cart
cartpops_get_free_upsell_products_count_in_cart, cartpops_get_rule_products_count_in_cart
cartpops_get_upsell_products_in_cart, cartpops_get_free_upsells_per_page_column_count
cartpops_get_carousel_options, cartpops_get_rule_translated_string
cartpops_get_address_metas, cartpops_get_address, cartpops_get_product
cartpops_cart_item_price, cartpops_cart_item_thumbnail, cartpops_cart_item_product
cartpops_cart_item_product_name, cartpops_get_quantity_from_cart_item
cartpops_after_cart_item_name, cartpops_render_product_image
cartpops_implode_html_attributes, cartpops_mapped_implode, cartpops_check_is_array
cartpops_outbound_url, cartpops_get_emoji_flag, cartpops_set_cart_constant
cartpops_create_new_rule, cartpops_get_rule, cartpops_update_rule, cartpops_delete_rule
cartpops_create_new_master_log, cartpops_get_master_log, cartpops_update_master_log
cartpops_delete_master_log, cartpops_select2_html, cartpops_get_datepicker_html

AJAX endpoints and fragments

V1 registered ten admin-ajax.php actions, each as wp_ajax_ and wp_ajax_nopriv_. They returned HTML fragments keyed by CSS selector and did not verify a nonce. None was documented. V2 removes all of them.

V2 requests authenticate with a WooCommerce Cart-Token header and a nonce. CartPops also accepts requests only from your site’s own origins and rate limits them per client. See Store API and REST. V1 registered no wc-ajax handlers of its own.

Fragments

V1 filtered woocommerce_add_to_cart_fragments to return HTML keyed by selector, and its JavaScript called replaceWith() for each one. These keys are gone:

.cpops-drawer-cart, div.cpops-drawer-notices-wrapper, div.cpops-cart-total
div.cpops-coupon-remove, div.cpops-drawer-recommendations-wrapper
div#cpops-floating-cart, .cpops-free-shipping-meter
.cartpops-cart__container-counter, .cartpops-cart__container-text
.cpops-popup-recommend-products, .cpops-added-product-item, div.cpops-assistant-items

V2 emits a single fragment, .cartpops-cart-json: an inert script element of type application/json that carries lightweight cart state, so a classic add can skip a second request. The visible cart updates from Interactivity API state.

Triggers, IDs and data attributes

V1 had no URL, hash or query-string trigger, and V2 has none either.

CSS classes and custom properties

The class prefixes are unchanged: cpops- and cartpops-. The structure underneath changed, so only part of the V1 class set exists in V2. Your Custom CSS is migrated and loaded after the CartPops styles. See CSS customization.

Kept as aliases on the current element:

Removed: the V1 cart row internals (.cpops-cart-item__quantity*, __product*, .cpops-cart-line-items, .cpops-restore-item), totals and coupon-tag wrappers, notices, the Splide slider (.cpops-slider*), the V1 component kit (.cpops-button, .cpops-label*, .cpops-collapse*, .cpops-tooltip*), the circular meter, and all popup, bar and assistant classes. Selectors that depend on V1 wrapper depth, sibling order or :nth-child are unsupported.

Custom properties: V1 --color-cpops-* and --cpops-width-drawer-* variables set on :root keep working through a two-way bridge, and the live element exposes the effective value under the V1 name too. Setting a V1 variable on a narrower element is not supported. Use the current V2 name. --cpops-animation-duration and --cpops-border-radius kept their names. Removed: --color-cpops-button-hover-opacity, --color-cpops-loader-color, --cpops-white-space-text (now the Product name display setting), and the slider and popup colors.

The full variable mapping lives in CSS customization.

Code migrations

Open the drawer from a custom button

In V1, any element with cpops-toggle-drawer, or a call to CartPops.drawer.show(), opened the drawer.

jQuery( '.my-cart-button' ).on( 'click', function ( e ) {
	e.preventDefault();
	CartPops.drawer.show();
} );

In V2, dispatch cartpops:open on document when the user clicks.

document.addEventListener( 'click', function ( event ) {
	if ( ! event.target.closest( '.my-cart-button' ) ) {
		return;
	}
	event.preventDefault();
	document.dispatchEvent( new CustomEvent( 'cartpops:open' ) );
} );

Give the link a real href (your cart page) so it still works if the click happens before the drawer script has loaded. Use cartpops:close and cartpops:toggle the same way.

Keep a header counter in sync

V1 code usually listened for jQuery cart events or returned its own WooCommerce fragment. In V2, render the starting count on the server and update it from cartpops:count-updated.

<span class="my-cart-count">
	<?php echo (int) ( WC()->cart ? WC()->cart->get_cart_contents_count() : 0 ); ?>
</span>

document.addEventListener( 'cartpops:count-updated', function ( event ) {
	document.querySelectorAll( '.my-cart-count' ).forEach( function ( el ) {
		el.textContent = event.detail.count;
	} );
} );

A fragment-based counter can keep working, because WooCommerce still applies woocommerce_add_to_cart_fragments and CartPops asks WooCommerce to refresh fragments after its own changes. That depends on WooCommerce’s cart-fragments script being loaded, and many themes and speed plugins remove it. The event does not depend on that script.

Add a line under the product name

In V1, you printed HTML after the item name.

add_action( 'woocommerce_after_cart_item_name', function ( $cart_item, $cart_item_key ) {
	if ( ! empty( $cart_item['my_engraving'] ) ) {
		echo '<div class="my-engraving">Engraving: ' . esc_html( $cart_item['my_engraving'] ) . '</div>';
	}
}, 10, 2 );

In V2, add a row to extraLines with cartpops_cart_item_data.

add_filter(
	'cartpops_cart_item_data',
	static function ( array $item, array $cart_item, string $cart_key ): array {
		if ( empty( $cart_item['my_engraving'] ) ) {
			return $item;
		}

		$item['extraLines'][] = array(
			'label' => __( 'Engraving', 'my-plugin' ),
			'value' => (string) $cart_item['my_engraving'],
		);
		return $item;
	},
	10,
	3
);

If your data is already exposed through WooCommerce’s standard woocommerce_get_item_data filter, CartPops shows it in the drawer without extra code.

extraLines are plain text. Tags and control characters are stripped, and the drawer never runs row HTML. You can add at most 20 rows, with a label up to 160 bytes and a value up to 1,000 bytes. CartPops ignores overrides of price, quantity, key, link and image. The same filter also runs for Store API responses, so the lines survive quantity and remove updates. For custom client code, customPresentation carries a bounded map under your own plugin key. See PHP filters.

Change the checkout URL

The filter name and call are the same as in V1.

add_filter( 'cartpops_checkout_button_url', function ( $url ) {
	return home_url( '/express-checkout/' );
} );

What changed is validation. CartPops accepts an absolute HTTP or HTTPS URL with a host, or a root-relative path such as /express-checkout/. A bare relative value such as express-checkout, a protocol-relative URL, a URL with credentials or an unsupported scheme falls back to the WooCommerce checkout URL. Return a raw URL, not HTML. cartpops_empty_cart_button_url follows the same rules.

Add classes

V1 filters such as cartpops_drawer_classes are not applied in V2. There is no filter that adds classes to CartPops-owned elements, and an action cannot do it either. Use CSS. Many elements keep their V1 class names, so you can scope your rules with a class on body.

add_filter( 'body_class', function ( $classes ) {
	$classes[] = 'my-cartpops-skin';
	return $classes;
} );

.my-cartpops-skin .cpops-drawer {
	--cpops-primary: #1d4ed8;
}

In Pro, the secondary drawer button still supports extra classes through cartpops_secondary_btn_classes. It is additive only.

add_filter( 'cartpops_secondary_btn_classes', function ( array $classes, string $mode ): array {
	$classes[] = 'my-secondary-button';
	return $classes;
}, 10, 2 );

Guard fs_cartpops()

fs_cartpops() and cartpops_fs() return null when the Freemius bootstrap did not complete. A V1 snippet that calls a method directly on the result can fail with a fatal error.

$fs = function_exists( 'fs_cartpops' ) ? fs_cartpops() : null;
if ( null === $fs ) {
	return;
}

Related

• Upgrading to V2
• PHP actions
• PHP filters
• JavaScript
• Store API and REST
• CSS customization