Hooks and filters reference

Cartavera and the Cartavera Blocks plugin provide the 15 filters below. There are no custom actions. Every example on this page was run on a test site with Cartavera 1.3.0 and Cartavera Blocks 1.2.0.

Where to put this code

Put it in a small plugin of your own, or in a child theme‘s functions.php. Don’t edit Cartavera’s own files: theme updates replace them.

A minimal plugin is a single file in wp-content/plugins/my-store-tweaks/my-store-tweaks.php:

<?php
/**
 * Plugin Name: My store tweaks
 */

defined( 'ABSPATH' ) || exit;

// Your add_filter() calls go here.

Activate it under Plugins.

Quick reference

Filter	From	Changes
cartavera_purchase_notes	Plugin	Notes under the add-to-cart button
cartavera_free_shipping_progress	Plugin	Whether free-shipping progress shows
cartavera_new_badge_days	Plugin	How long a product counts as “New”
cartavera_best_sellers_cache_ttl	Plugin	How often best-seller badges are recalculated
cartavera_size_guide_id	Plugin	Which size guide a product uses
cartavera_wishlist_provider	Plugin	Which wishlist plugin’s button shows
cartavera_quick_view_cache	Plugin	Whether quick view markup is cached
cartavera_track_recently_viewed	Plugin	Whether recently viewed products are recorded
cartavera_blocks_demo_starters	Plugin	Which starter sites the importer offers
cartavera_store_facts	Theme	Facts in the trust and FAQ patterns
cartavera_newsletter_url	Theme	Link of the newsletter Sign up buttons
cartavera_under_price_amount	Theme	Price limit of “Products under a price”
cartavera_companion_plugin_package	Theme	Where the Cartavera Blocks installer gets the plugin
cartavera_license_store_url	Theme	Licence and update server
cartavera_license_item_id	Theme	Product ID sent to the licence server

Plugin filters only run while Cartavera Blocks is active. Theme filters only run while Cartavera (or a child theme of it) is the active theme.

Product page

cartavera_purchase_notes

Filters the notes shown under the add-to-cart button by the Purchase Notes block. Use it to add real information from your own systems: delivery estimates from your shipping provider, warranty terms, pickup details.

Parameter	Type	Description
$notes	array	Notes keyed by ID. Each note is array( 'icon' => string, 'html' => string )
$product	WC_Product	The product being shown

Return the notes array. Built-in keys: delivery, seller, returns, secure; each is only present when it applies (see Purchase notes).

• icon: one of truck, box, return, lock, download, clock, ruler, cart, user, search, menu, close, chevron, chevron-r, chevron-l. An unknown name shows nothing in the icon’s place.
• html: passed through wp_kses_post(), so links and <strong> work and scripts are removed. Escape your own text anyway.

Return an empty array to hide the block.

// Add a warranty note to products in the "electronics" category or any of its subcategories.
add_filter( 'cartavera_purchase_notes', function ( $notes, $product ) {
	$electronics = get_term_by( 'slug', 'electronics', 'product_cat' );
	if ( ! $electronics ) {
		return $notes;
	}
	foreach ( $product->get_category_ids() as $cat_id ) {
		if ( $cat_id === $electronics->term_id || term_is_ancestor_of( $electronics, $cat_id, 'product_cat' ) ) {
			$notes['warranty'] = array(
				'icon' => 'lock',
				'html' => esc_html__( '2-year manufacturer warranty', 'my-store' ),
			);
			break;
		}
	}
	return $notes;
}, 10, 2 );

// Remove the "Sold by" line everywhere.
add_filter( 'cartavera_purchase_notes', function ( $notes ) {
	unset( $notes['seller'] );
	return $notes;
} );

Only add statements that are true for every shopper who sees them. A delivery estimate, for example, should come from data that knows the shopper’s location and the product’s stock.

cartavera_size_guide_id

Filters which size guide a product uses. A size guide is a synced pattern (wp_block post).

Parameter	Type	Description
$guide	int	Synced pattern ID found on the product’s categories (nearest first), or 0 for none
$product	WC_Product	The product

Return a synced pattern ID, or 0 to show no size guide.

The filter runs for products set to Use the category’s guide (the default). A product with its own guide, or set to None, keeps that choice and the filter isn’t called.

// Use one guide (synced pattern 123) for every product tagged "shoes"
// that has no guide of its own.
add_filter( 'cartavera_size_guide_id', function ( $guide, $product ) {
	if ( ! $guide && has_term( 'shoes', 'product_tag', $product->get_id() ) ) {
		return 123;
	}
	return $guide;
}, 10, 2 );

cartavera_wishlist_provider

Filters which wishlist the Wishlist Button block uses.

Parameter	Type	Description
$provider	string	woocommerce, yith, ti, or '' for none. Detected in that order

Return one of those values. Return a provider only when its plugin is active.

// Prefer YITH WooCommerce Wishlist even when WooCommerce's own wishlist is on.
add_filter( 'cartavera_wishlist_provider', function ( $provider ) {
	return shortcode_exists( 'yith_wcwl_add_to_wishlist' ) ? 'yith' : $provider;
} );

// Hide the Wishlist Button block everywhere.
add_filter( 'cartavera_wishlist_provider', '__return_empty_string' );

Catalog

cartavera_new_badge_days

Filters how many days after publishing a product shows the “New” badge. It overrides the Product Badges block setting (default 30).

Parameter	Type	Description
$days	int	Days from the block setting
$product	WC_Product	The product

Return a number of days. 0 or less means never “New”.

// "New" means the last 14 days everywhere.
add_filter( 'cartavera_new_badge_days', function () {
	return 14;
} );

has_term() matches products assigned to that exact category, not to its subcategories; see the cartavera_purchase_notes example above for a check that includes subcategories.

// Never show "New" on products in the "clearance" category.
add_filter( 'cartavera_new_badge_days', function ( $days, $product ) {
	return has_term( 'clearance', 'product_cat', $product->get_id() ) ? 0 : $days;
}, 10, 2 );

cartavera_best_sellers_cache_ttl

Filters how long best-seller rankings are cached, in seconds. Rankings are also cleared whenever a product or category is saved or deleted.

Parameter	Type	Description
$ttl	int	Seconds. Default 6 * HOUR_IN_SECONDS

// Recalculate best sellers every hour.
add_filter( 'cartavera_best_sellers_cache_ttl', function () {
	return HOUR_IN_SECONDS;
} );

A shorter time means more database queries. On a large catalog, keep it at an hour or more.

cartavera_quick_view_cache

Filters whether the quick view pop-up’s markup is cached. It’s cached per product, language, currency and modification date, and cleared when stock or products change.

Parameter	Type	Description
$cache	bool	true, except when prices are shown including tax worked out from the shopper’s address
$product	WC_Product	The product

Turn caching off when the markup can differ between shoppers in a way Cartavera can’t see, for example role-based or customer-group prices.

// Never cache quick view (role-based prices).
add_filter( 'cartavera_quick_view_cache', '__return_false' );

cartavera_track_recently_viewed

Filters whether product pages record the product in the shopper’s recently viewed list. The list lives only in the shopper’s browser (localStorage key cartavera_recently_viewed). It’s never sent to your server or stored in a cookie.

Parameter	Type	Description
$track	bool	Default true

// Stop recording recently viewed products.
add_filter( 'cartavera_track_recently_viewed', '__return_false' );

Products already in a shopper’s list still show in the Recently Viewed block. Remove the block from your templates as well if you want the section gone.

Cart

cartavera_free_shipping_progress

Filters whether the “Spend $X more for free shipping” message is shown in the cart and mini-cart.

Parameter	Type	Description
$enabled	bool	The Free shipping progress setting (WooCommerce → Settings → Shipping → Shipping options), and false when shipping is disabled

// Turn free-shipping progress off.
add_filter( 'cartavera_free_shipping_progress', '__return_false' );

// Show it only to signed-in customers.
add_filter( 'cartavera_free_shipping_progress', function ( $enabled ) {
	return $enabled && is_user_logged_in();
} );

The message is also added to the Store API cart response, so the filter controls the Cart block, the mini-cart and API responses together.

Patterns

These filters run when Cartavera renders a pattern from the theme. A pattern you’ve inserted into a page and saved, or a template you’ve edited and saved in the Site Editor, keeps its saved content, and these filters no longer change it.

cartavera_store_facts

Filters the facts that the trust and FAQ patterns (How shopping here works, Accepted payment methods, Store rating summary, Shopping FAQ, Store information) read from your store settings. A key that’s missing means “not set up”, and the pattern leaves that line out.

Parameter	Type	Description
$facts	array	See the keys below

Key	Type	Present when
https	bool	The site uses HTTPS
payments	string[]	Titles of the enabled payment methods
guest	bool	Guest checkout is on
account_url, orders_url	string	WooCommerce is active
returns, terms	array( url, title )	WooCommerce’s Refund and Returns Policy page, or the terms and conditions page (WooCommerce → Settings → Advanced → Page setup), is published
free_shipping	array( 'min' => float, 'everywhere' => bool )	A Free Shipping method has a minimum amount
ships_anywhere	bool	You sell to all countries and the “rest of the world” zone has methods
ships_to	string[]	You ship to six countries or fewer
reviews	array( 'count' => int, 'average' => float )	There’s at least one approved product review
address	string	A store address is set in WooCommerce → Settings → General

Only add or change facts that are true for every shopper who sees them.

// Don't list payment methods in the trust and FAQ patterns.
add_filter( 'cartavera_store_facts', function ( $facts ) {
	unset( $facts['payments'] );
	return $facts;
} );

// Link the trust and FAQ patterns to your own returns page instead of WooCommerce's
// "Refund and Returns Policy" page.
add_filter( 'cartavera_store_facts', function ( $facts ) {
	$page = get_page_by_path( 'returns-and-exchanges' );
	if ( $page && 'publish' === $page->post_status ) {
		$facts['returns'] = array( get_permalink( $page ), get_the_title( $page ) );
	}
	return $facts;
} );

The review count and average are cached for an hour and refreshed when a review changes.

cartavera_newsletter_url

Filters the link of the Sign up button in every newsletter pattern (Newsletter banner, Newsletter with image, Newsletter strip, Footer with newsletter sign-up).

Parameter	Type	Description
$url	string	Default #newsletter

// Send every newsletter button to your email provider's sign-up page.
add_filter( 'cartavera_newsletter_url', function () {
	return 'https://example.com/newsletter-signup';
} );

The URL goes through esc_url().

cartavera_under_price_amount

Filters the price limit of the Products under a price pattern, in your store currency. Its heading (“Under $25”) and its “See everything at this price” link to the filtered shop follow the same amount.

Parameter	Type	Description
$amount	int	Default 25

// "Under $50" instead of "Under $25".
add_filter( 'cartavera_under_price_amount', function () {
	return 50;
} );

This changes new insertions of the pattern. A copy you’ve already inserted and saved keeps its own amount; change it in the block’s price range settings.

Setup and licensing

cartavera_companion_plugin_package

Filters where the Install and activate Cartavera Blocks button gets the plugin.

Parameter	Type	Description
$package	string	Path to bundled/cartavera-blocks.zip in the theme, or '' when it’s missing

Return an absolute path to a ZIP on the server, or an https:// URL. Anything else is ignored. The package is never taken from the request, and WordPress.org is never asked for it.

// Install Cartavera Blocks from a ZIP in uploads (for example a newer build).
add_filter( 'cartavera_companion_plugin_package', function () {
	return WP_CONTENT_DIR . '/uploads/cartavera-blocks.zip';
} );

cartavera_license_store_url

Filters the store the licence client talks to for activation, status checks and updates. You don’t need it for a normal install: the default is https://wpruby.com. It’s for testing against a staging store. The CARTAVERA_STORE_URL constant in wp-config.php does the same.

Parameter	Type	Description
$url	string	CARTAVERA_STORE_URL if defined, otherwise https://wpruby.com. A trailing slash is removed

add_filter( 'cartavera_license_store_url', function () {
	return 'https://staging.example.com';
} );

cartavera_license_item_id

Filters the Easy Digital Downloads product ID sent with licence requests. The default is Cartavera’s ID on wpruby.com, 91969. The CARTAVERA_EDD_ITEM_ID constant does the same.

Parameter	Type	Description
$item_id	int	CARTAVERA_EDD_ITEM_ID if defined, otherwise 91969

add_filter( 'cartavera_license_item_id', function () {
	return 1234; // The download's ID on your staging store.
} );

Starter sites

cartavera_blocks_demo_starters

Filters the starter sites offered on Tools → Cartavera Sample Store and by wp cartavera demo starters.

Parameter	Type	Description
$starters	array[]	Starters keyed by slug: marketplace, electronics, fashion, grocery

Each starter has label, description, style (a file name in the theme’s styles/ folder, or ''), header and footer (pattern slugs, or ''), front (homepage template slug, or ''), data (a function that returns the catalog, or '' for the marketplace data), size_guide (category slugs) and features_page (bool).

// Offer only the Fashion and Grocery starters.
add_filter( 'cartavera_blocks_demo_starters', function ( $starters ) {
	return array_intersect_key( $starters, array_flip( array( 'fashion', 'grocery' ) ) );
} );

// Import the Fashion catalog without changing the site's design.
add_filter( 'cartavera_blocks_demo_starters', function ( $starters ) {
	$starters['fashion']['style']  = '';
	$starters['fashion']['header'] = '';
	$starters['fashion']['footer'] = '';
	$starters['fashion']['front']  = '';
	return $starters;
} );

Removing a starter from this list while it’s installed doesn’t remove its content. Remove it from the importer screen first.

WooCommerce hooks Cartavera uses

For reference when you debug a conflict. Cartavera overrides no WooCommerce PHP templates.

Hook	What Cartavera does
woocommerce_breadcrumb_defaults	Breadcrumb separator (›)
woocommerce_product_thumbnails_columns	Five gallery thumbnails per row
woocommerce_single_product_image_thumbnail_html	Lazy-loads gallery slides after the first
woocommerce_hooked_blocks_pattern_exclude_list	Stops WooCommerce adding a second account icon to Cartavera’s headers
render_block_woocommerce/product-filter-checkbox-list	Adds role="img" to the rating filter’s stars, for screen readers
render_block_woocommerce/product-filters, render_block_woocommerce/mini-cart	Loads the small scripts that manage keyboard focus in the filter overlay and mini-cart drawer

Other extension points

Constants

Define these in wp-config.php:

Constant	Effect
CARTAVERA_STORE_URL	Licence and update server. Default https://wpruby.com
CARTAVERA_EDD_ITEM_ID	Product ID sent to the licence server. Default 91969

CSS custom properties

Property	Default	Use
--cv-focus-color	The Hyperlink colour (the On header colour inside the header and footer)	Keyboard focus rings. Set it on any dark section you add so the ring stays visible
--cv-search-border	The form field border colour	Outline of the Store Search bar. Cartavera’s header sets it to transparent
--cv-search-focus	The Hyperlink colour	Focus ring of the Store Search bar. Cartavera’s header sets it to the Accent colour

The palette is available as --wp--preset--color--{slug}, for example --wp--preset--color--accent. The theme’s layout values are in --wp--custom--*, for example --wp--custom--grid--gap.

Data

What	Where
Free-shipping progress	Store API cart responses (/wp-json/wc/store/v1/cart), under extensions.cartavera.free_shipping
Quick view markup	GET /wp-json/cartavera-blocks/v1/quick-view/<product-id>. Published, catalog-visible products without a password only
Recently viewed	localStorage key cartavera_recently_viewed in the shopper’s browser
Sample content	Every object the starter importer creates has the _cartavera_demo meta key

Block names

Blocks keep the cartavera/ namespace: cartavera/product-search, category-drawer, account-menu, product-rating, product-discount, purchase-notes, sticky-purchase-bar, recently-viewed, category-grid, mega-menu, product-badges, sale-countdown, size-guide and wishlist-button. Quick view is the cartaveraQuickView attribute on WooCommerce’s Product Template block.