Themology
Docs Bouncer

Geo Protection

Geo Protection#

Bouncer includes two country-based features: geo-blocking and CAPTCHA exclusion. Geo-blocking lets you block entire countries from accessing your site. CAPTCHA exclusion skips verification for visitors from trusted countries. Both rely on GeoIP lookup to determine the visitor’s country.

How GeoIP works#

The plugin resolves a visitor’s country in two steps.

First, it tries WC_Geolocation::geolocate_ip(), which uses the local MaxMind GeoLite2 database when you’ve configured WooCommerce geolocation. This is the fastest and most private option since everything stays on your server.

If WooCommerce geolocation isn’t set up, it falls back to the ip-api.com free tier. This works out of the box but sends the visitor’s IP over HTTP and is rate limited to 45 requests per minute.

The client IP is resolved through WC_Geolocation::get_ip_address(), which correctly handles Cloudflare, reverse proxies, and load balancers. Results are cached in WordPress transients for 1 hour per IP, so repeated requests from the same visitor don’t trigger additional lookups.

To override the resolved country programmatically, use the cfwc_geoip_country_code filter:

add_filter( 'cfwc_geoip_country_code', function ( $country_code, $ip_address ) {
    // Force US for a specific IP range.
    if ( str_starts_with( $ip_address, '192.168.' ) ) {
        return 'US';
    }
    return $country_code;
}, 10, 2 );

Geo-blocking#

What it does#

Blocks visitors from specified countries from accessing your entire site. Blocked visitors see a configurable 403 page with a custom message. No other content loads.

Configuration#

  1. Go to WooCommerce > Settings > Bouncer > Security.
  2. Find the Blocked countries field. It uses WooCommerce’s searchable country selector (WooSelect2), so you can type to search and select multiple countries.
  3. Set the Blocked country message to the text you want blocked visitors to see.

How it works#

The blocker hooks into template_redirect at priority 1, so it runs before anything else renders. When a visitor’s country matches the blocked list, the plugin sends a 403 status code, renders an HTML page with your custom message, and exits.

It skips admin pages (is_admin()), AJAX requests, and REST API calls to avoid breaking backend functionality. The blocker class is a singleton and only gets instantiated when you’ve configured at least one blocked country.

Use cases#

  • Block countries you don’t ship to.
  • Block regions with high fraud volume.
  • Comply with sanctions or trade restrictions.

Country-based CAPTCHA exclusion#

What it does#

Skips CAPTCHA verification for visitors from countries you trust. This removes friction for your known customer base while keeping protection active for everyone else.

Configuration#

  1. Go to WooCommerce > Settings > Bouncer > Security.
  2. Find the Excluded countries field. It uses the same searchable country selector as geo-blocking.
  3. Select the countries where CAPTCHA should be skipped.

When a visitor’s country matches an excluded country, the plugin’s cfwc_skip_verification filter returns true, bypassing CAPTCHA on all protected forms.

Use cases#

  • Your store mainly serves US customers. Skip CAPTCHA for US visitors to reduce checkout friction.
  • You have high trust in certain regions and want a smooth experience there.
  • Combine with fraud scoring. CAPTCHA gets skipped, but fraud scoring still evaluates orders at checkout. You keep the safety net without the extra step.

Setting up WooCommerce geolocation#

For the best results, configure WooCommerce’s built-in geolocation. It uses a local database, works over HTTPS, and doesn’t depend on external APIs.

  1. Go to WooCommerce > Settings > General.
  2. Under Default customer location, select Geolocate.
  3. WooCommerce will download and use the MaxMind GeoLite2 database automatically.

If WooCommerce geolocation isn’t configured, the plugin falls back to ip-api.com. That means visitor IPs get sent over HTTP (free tier limitation) and you’re subject to a 45 request per minute rate limit.

Privacy#

How each method handles visitor data:

  • WooCommerce with MaxMind: All lookups happen locally. No external calls. This is the recommended setup.
  • ip-api.com fallback: Sends the visitor’s IP address to ip-api.com over HTTP. No other personal information is transmitted.
  • Caching: Results are stored locally in WordPress transients. Nothing leaves your server after the initial lookup.
  • Fraud Scoring covers fraud rules that use GeoIP data for risk assessment.
  • Settings has the full configuration reference for all Bouncer options.