ZiziCache

RC Beta

Join the Beta β

How to Manage Cache Exclusions and Bypass Rules?

Updated on 10. 2. 2026

Overview

Cache exclusions (bypass rules) determine when ZiziCache must skip page caching to keep dynamic or personalized content correct. ZiziCache also supports cache variants (mobile, role, language, currency, cart state) which are different from exclusions.

Where to configure

  • Admin UI: ZiziCache → Cache → Exclusions
  • REST API: /wp-json/zizi-cache/v1/cache-exclusions
  • Config keys: cache_bypass_urls, cache_bypass_cookies, cache_ignore_queries, cache_include_queries, cache_logged_in, cache_separate_mobile

Built‑in bypass rules (always applied)

  • Only GET/HEAD requests are cacheable (POST/PUT/DELETE are bypassed).
  • REST API requests (/wp-json/) are bypassed.
  • WP‑CLI context is bypassed.
  • Preload/warm requests are bypassed (?zizi_preload=1, ?zizi_warmed=1, or headers X-Zizi-Preload/X-Zizi-Warmed).
  • Manual bypass URL params are honored: , ?nocache=1, ?bypass_optimization=1, ?zizi_bypass=1.
  • Page builder/editor query parameters (Elementor, Bricks, Divi, etc.) are bypassed.
  • WooCommerce dynamic cookies and query parameters are bypassed (see below).
  • Logged‑in users are bypassed when cache_logged_in is disabled.
  • Admin/AJAX/AMP/password‑protected or non‑HTML responses are not cached.
  • System URLs (e.g. wp-admin, wp-login.php, wp-cron.php, sitemap/feed/XML endpoints) are not cached.

URL bypass patterns

Use cache_bypass_urls to bypass matching URLs. The match is a simple case‑insensitive substring match.
/checkout/
/cart/
/my-account/
/wp-login.php
/?preview=

Cookie bypass patterns

Use cache_bypass_cookies to bypass when cookie names match (substring match). WooCommerce session cookies are bypassed by default.
wordpress_logged_in_
comment_author_
custom_session

Query parameter handling

  • Ignore list: cache_ignore_queries (tracking params are removed from the cache key).
  • Include list: cache_include_queries (creates cache variations per value).
  • Unknown params: by default, ZiziCache does not cache requests with unknown query parameters. Extend the whitelist via cache_include_queries or filter zizi_cache_known_query_params.
Default include list includes: lang, currency, orderby, min_price, max_price, rating_filter. The default ignore list is maintained in code and already contains common marketing parameters (UTM, FB, Google Ads, etc.).

Logged‑in users & roles

  • cache_logged_in enables caching for logged‑in users.
  • ZiziCache sets a cookie zc_logged_in_roles and can create separate cache files per role.
  • Exclude roles via filter zizi_cache_cache_excluded_roles.

Page builders / preview modes

Requests with editor parameters are bypassed automatically. Examples:
elementor-preview
bricks
et_fb
fl_builder
ct_builder
vc_editable
Extend the list via zizi_cache_page_builder_params.

WooCommerce specifics

Bypassed cookies (built‑in):
woocommerce_cart_hash
woocommerce_items_in_cart
wp_woocommerce_session_
woocommerce_recently_viewed
Bypassed query params (built‑in):
add-to-cart
remove_item
update_cart
undo_item
order-pay
order-received
wc-ajax
key
WooCommerce page paths (cart/checkout/account) are detected and bypassed when configured. If cart items exist, a -cart cache variant is used.

Mobile & device handling

  • cache_separate_mobile creates -mobile cache variants.
  • Tablets are treated as desktop by default. Adjust with zizi_cache_tablet_is_mobile or zizi_cache_is_mobile.

Useful filters

  • zizi_cache_is_cacheable
  • zizi_cache_cache_excluded_roles
  • zizi_cache_page_builder_params
  • zizi_cache_known_query_params
  • zizi_cache_request_uri
  • zizi_cache_cache_file_path
  • zizi_cache_cache_file_name
// Example: allow a custom query parameter
add_filter('zizi_cache_known_query_params', function($params) {
    $params[] = 'custom_param';
    return $params;
});

How to test exclusions

  • Check response headers: x-zizi-cache-cache (HIT/MISS/BYPASS/EXPIRED).
  • Verify cache files in /wp-content/cache/zizi-cache/.
  • Use , ?nocache=1, ?bypass_optimization=1 or ?zizi_bypass=1 to force bypass when testing.
  • Review the log file: /wp-content/plugins/zizi-cache/zizi-log.log.
What are your feelings