---
title: Hooks and filters reference
description: Every filter Cartavera and Cartavera Blocks provide, with examples, plus constants, CSS variables and data endpoints.
url: "https://wpruby.com/knowledgebase/cartavera-hooks/"
updated: "2026-11-04"
category: WPRuby Themes / Cartavera
---

# 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.

Table of Contents

 [Toggle](#)

- [Where to put this code](#Where_to_put_this_code)
- [Quick reference](#Quick_reference)
- [Product page](#Product_page)
  - [cartavera_purchase_notes](#cartavera_purchase_notes)
  - [cartavera_size_guide_id](#cartavera_size_guide_id)
  - [cartavera_wishlist_provider](#cartavera_wishlist_provider)
- [Catalog](#Catalog)
  - [cartavera_new_badge_days](#cartavera_new_badge_days)
  - [cartavera_best_sellers_cache_ttl](#cartavera_best_sellers_cache_ttl)
  - [cartavera_quick_view_cache](#cartavera_quick_view_cache)
  - [cartavera_track_recently_viewed](#cartavera_track_recently_viewed)
- [Cart](#Cart)
  - [cartavera_free_shipping_progress](#cartavera_free_shipping_progress)
- [Patterns](#Patterns)
  - [cartavera_store_facts](#cartavera_store_facts)
  - [cartavera_newsletter_url](#cartavera_newsletter_url)
  - [cartavera_under_price_amount](#cartavera_under_price_amount)
- [Setup and licensing](#Setup_and_licensing)
  - [cartavera_companion_plugin_package](#cartavera_companion_plugin_package)
  - [cartavera_license_store_url](#cartavera_license_store_url)
  - [cartavera_license_item_id](#cartavera_license_item_id)
- [Starter sites](#Starter_sites)
  - [cartavera_blocks_demo_starters](#cartavera_blocks_demo_starters)
- [WooCommerce hooks Cartavera uses](#WooCommerce_hooks_Cartavera_uses)
- [Other extension points](#Other_extension_points)
  - [Constants](#Constants)
  - [CSS custom properties](#CSS_custom_properties)
  - [Data](#Data)
  - [Block names](#Block_names)

## Where to put this code

Put it in a small plugin of your own, or in a [child theme](https://wpruby.com/knowledgebase/cartavera-child-themes/)'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`](#cartavera_purchase_notes) | Plugin | Notes under the add-to-cart button |
| [`cartavera_free_shipping_progress`](#cartavera_free_shipping_progress) | Plugin | Whether free-shipping progress shows |
| [`cartavera_new_badge_days`](#cartavera_new_badge_days) | Plugin | How long a product counts as "New" |
| [`cartavera_best_sellers_cache_ttl`](#cartavera_best_sellers_cache_ttl) | Plugin | How often best-seller badges are recalculated |
| [`cartavera_size_guide_id`](#cartavera_size_guide_id) | Plugin | Which size guide a product uses |
| [`cartavera_wishlist_provider`](#cartavera_wishlist_provider) | Plugin | Which wishlist plugin's button shows |
| [`cartavera_quick_view_cache`](#cartavera_quick_view_cache) | Plugin | Whether quick view markup is cached |
| [`cartavera_track_recently_viewed`](#cartavera_track_recently_viewed) | Plugin | Whether recently viewed products are recorded |
| [`cartavera_blocks_demo_starters`](#cartavera_blocks_demo_starters) | Plugin | Which starter sites the importer offers |
| [`cartavera_store_facts`](#cartavera_store_facts) | Theme | Facts in the trust and FAQ patterns |
| [`cartavera_newsletter_url`](#cartavera_newsletter_url) | Theme | Link of the newsletter **Sign up** buttons |
| [`cartavera_under_price_amount`](#cartavera_under_price_amount) | Theme | Price limit of "Products under a price" |
| [`cartavera_companion_plugin_package`](#cartavera_companion_plugin_package) | Theme | Where the Cartavera Blocks installer gets the plugin |
| [`cartavera_license_store_url`](#cartavera_license_store_url) | Theme | Licence and update server |
| [`cartavera_license_item_id`](#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](https://wpruby.com/knowledgebase/cartavera-product-page/#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.