Docs Country Based Restrictions PRO for WooCommerce How CBR PRO Detects the Customer’s Country

How CBR PRO Detects the Customer’s Country

Every restriction in Country Based Restrictions PRO (CBR PRO) — product visibility, catalog rules, payment gateways — depends on one thing: knowing which country the customer is in. This page explains where that country comes from, in what order the sources are checked, and what can interfere with detection.

Detection Sources and Precedence

CBR PRO checks these sources in order and uses the first one that returns a country:

  • 1. The country the visitor selected — in the Country Detection widget or shortcode, or passed in the URL as ?country=XX (a two-letter country code). The selection is stored in a cookie named country.
  • 2. The customer’s address — the saved address of a logged-in customer, or the address a guest enters at checkout. Whether the billing or shipping country is used depends on the Restriction by country setting (default: shipping).
  • 3. IP geolocation — via WooCommerce’s MaxMind integration. This is the fallback for guest visitors who haven’t selected a country or entered an address. It requires a free MaxMind license key (see below).
INFO
The Force geolocation setting (Settings → Restriction Settings, off by default) changes this order: it detects the country by IP geolocation even for logged-in customers, ignoring their saved address.

Payment gateway rules are a partial exception: each rule has its own Customer Country setting (billing or shipping, default billing), set per rule on the Payment Restrictions tab.

The MaxMind License Key (Required for IP Detection)

WooCommerce geolocation is not enabled by default. Since WooCommerce 3.9, IP-based detection requires a free MaxMind license key. Without it, guest visitors’ countries cannot be detected from their IP address, and restrictions only apply once the customer selects a country or enters an address.

WooCommerce → Settings → Integration → MaxMind Geolocation

Follow the step-by-step setup in Getting Started. In short: create a free MaxMind account, generate a license key, paste it into the integration settings, and set Default customer location to Geolocate in WooCommerce → Settings → General. CBR PRO keeps the MaxMind database updated automatically.

The country Cookie

When a visitor picks a country in the widget or shortcode (or arrives with ?country=XX in the URL), CBR PRO stores it in a cookie named country:

  • Lifetime: 30 days by default. It can be changed with the set_cookie_expiration filter (see Code Snippets).
  • Precedence: while the cookie is set, it overrides IP geolocation. When the customer commits a different country at checkout, the cookie is updated to match.
  • Privacy: the cookie stores only a two-letter country code, no personal data. If your store shows a cookie-consent banner, list it as a functional cookie.

Page Caching

Full-page caching is the most common reason detection “stops working”: a page geolocated for one visitor gets cached and served to everyone, regardless of their country.

  • Use WooCommerce’s caching-aware mode — in WooCommerce → Settings → General, set Default customer location to Geolocate (with page caching support). It detects the country in the browser, after the cached page loads.
  • CBR PRO excludes country-specific requests automatically — since version 4.3.6, any request with a country cookie, an active Country Detection widget, or a page containing the widget shortcodes is sent with no-cache headers (DONOTCACHEPAGE). This is honored by WP Super Cache, W3 Total Cache, WP Rocket, WP Fastest Cache, LiteSpeed Cache, and most hosting-level caches.
  • Check your cache plugin’s settings — see the plugin-specific guides for WP Rocket and Speed Optimizer by SiteGround.

Accuracy, VPNs, and Testing

  • IP geolocation is approximate. Visitors using a VPN or proxy are detected in the VPN server’s country, not their own. The Country Detection widget gives them a way to correct it.
  • To see what the plugin detects, enable the debug toolbar (Settings → Restriction Settings → Enable debug toolbar, off by default). It shows the detected country at the top of the storefront.
  • To test as a visitor from a specific country, open your store with ?country=XX appended to the URL (for example ?country=DE), or use the widget to switch countries. Clear the country cookie to return to IP-based detection.

Next Steps