WooCommerce Country Block Manual

A Different Approach to Country Restrictions in WooCommerce

Most WooCommerce country restriction plugins focus on hiding specific products, prices, or add to cart buttons based on the visitor’s location.

WooCommerce Country Block takes a different approach.

Instead of selectively hiding parts of your store, it blocks access to the entire site for selected countries. Visitors from those countries are not served your normal website content. They see either a dedicated unavailable page from your site or a simple built-in message.

This approach is especially useful when you want a clear site-wide rule instead of complicated partial restrictions. For example, if you do not want to serve visitors from certain regions because of privacy, legal, or business reasons, this plugin gives you a simple and predictable way to do it.

The plugin is privacy-focused by design:

• No tracking
• No telemetry
• No analytics
• No external requests made by the plugin
• No front-end scripts required for blocking

What This Plugin Does

WooCommerce Country Block checks the visitor’s country before your page is shown.

If the visitor is from a blocked country, the plugin:

• stops your normal site from loading
• sends an HTTP 503 Service Unavailable response
• applies noindex and no-cache headers
• shows either your /unavailable page or the plugin’s built-in message page

If the visitor is from an allowed country, your website works normally.

There are no redirects. The browser stays on the same URL the visitor originally requested.

Requirements

To use the plugin, you need:

• WordPress 6 or newer
• WooCommerce installed and active
• PHP 7.4 or newer

Cloudflare is optional, but recommended if you use it on your site, because the plugin can use Cloudflare’s country header when available.

If WooCommerce or its geolocation class is not available, the plugin safely does nothing instead of breaking your site.

Installation

1. In WordPress admin, go to Plugins → Add New.
2. Click Upload Plugin.
3. Upload the plugin ZIP file.
4. Click Install Now.
5. Click Activate.

After activation, the plugin adds its settings page under:

WordPress Admin → Settings → Country Block

You will also see a Settings link directly in the Plugins list.

Quick Setup

If you want the plugin working in a minute or two, do this:

1. Go to Settings → Country Block.
2. In Blocked ISO-2 codes, enter the countries you want to block, separated by commas.
3. Click Save Changes.

Example:

RU, NG, PK

After saving, visitors from those countries will be blocked.

Where to Find the Settings

Open:

WordPress Admin → Settings → Country Block

On this page, you can configure:

• blocked countries
• custom heading
• custom message
• apology message
• text color
• background color

The settings page also includes a link to the online documentation and a direct explanation of what the plugin does.

Settings Explained

Blocked ISO-2 codes

This is the main setting.

Where:
Settings → Country Block → Blocked ISO-2 codes

What to enter:
A comma-separated list of 2-letter country codes.

Example:

RU, NG, PK

The plugin accepts valid ISO-2 country codes only. Invalid entries are ignored when you save. Country codes are normalized automatically, so lowercase entries are converted to uppercase.

If you leave this empty on a fresh setup, the plugin uses its built-in default blocked list. That default list in the code is:

BD, BY, CZ, DZ, ID, IR, KP, NG, PK, RU, SK

Custom heading

Where:
Settings → Country Block → Custom heading (optional)

This is the main title shown to blocked visitors when the built-in message page is being used.

If you leave it empty, the plugin uses its default heading:

Service is temporarily unavailable

Custom message

Where:
Settings → Country Block → Custom message (optional)

This is the main body text shown to blocked visitors when the built-in message page is being used.

If you leave it empty, the plugin uses its default message:

This website is temporarily unavailable. Access will be restored once the service is available again.

Important: if you enter any custom wording here, the plugin will use the built-in message page instead of your /unavailable page.

Apology message

Where:
Settings → Country Block → Apology message (optional)

This is a small line shown below the main message on the built-in message page.

If you leave it empty, the plugin uses its default apology line:

We apologize for any inconvenience.

Appearance

Where:
Settings → Country Block → Appearance (optional)

You can set:

• Text color (HEX)
• Background color (HEX)

Examples:

• #e6eef6
• #0f1720

These colors apply only to the blocked page or blocked message shown to visitors from blocked countries. Your normal website design is not changed for allowed visitors. Invalid color values are ignored, and the plugin falls back to its default colors.

Using Your Own /unavailable Page

If you want blocked visitors to see a page that matches your theme, you can create your own page.

How to do it

1. In WordPress admin, go to Pages → Add New.
2. Create a page.
3. Set the page slug to:

unavailable

1. Publish the page.

That is all.

What happens next

If a visitor from a blocked country accesses your website, the plugin will look for a published page with the slug unavailable.

If it exists, the plugin renders that page inside your theme. The visitor stays on the original requested URL. There is no redirect. The plugin simply shows the unavailable page content instead of the requested page.

Important rule

If you enter any custom heading, custom message, or apology text in the plugin settings, the plugin switches to the built-in message page and does not use /unavailable. This behavior is intentional.

So the rule is simple:

• No custom wording entered → use /unavailable if it exists
• Any custom wording entered → use the built-in message page

What Blocked Visitors See

Blocked visitors will see one of two things:

Option 1: Your /unavailable page

This is best if you want the blocked page to look like the rest of your website.

The plugin temporarily adds simple body classes and styling helpers so your chosen text and background colors can still apply during blocked rendering.

Option 2: The built-in message page

This is best if you want a very simple setup without creating a WordPress page.

The built-in page shows:

• the heading
• the main message
• the apology line

It uses the colors you set in the Appearance section, or the plugin defaults if you left them empty.

What Allowed Visitors See

Nothing unusual.

Allowed visitors do not see any message, no redirect, and no visual difference. Your site works normally for them.

How Country Detection Works

The plugin tries to detect the visitor’s country in a practical and safe way.

If Cloudflare is detected

The plugin uses CF-IPCountry, but only when Cloudflare really appears to be present. It checks Cloudflare-related server values instead of blindly trusting a header.

If Cloudflare is not detected

The plugin falls back to WooCommerce geolocation.

If the country cannot be determined

The plugin does not block the visitor. It allows access.

This is intentional safe fail-open behavior. It helps avoid accidental blocking when country detection is unavailable or uncertain.

Paths That Are Always Allowed

Some parts of WordPress are never blocked, even if the visitor’s country is on the blocked list.

These include:

• /wp-admin/
• /wp-login.php
• /wp-admin/admin-ajax.php
• /wp-cron.php
• /xmlrpc.php
• /.well-known/
• /unavailable

This is done so the site remains manageable and background tasks continue working properly. For example, you will not lock yourself out of the admin area because of your own settings.

The plugin also avoids blocking in other special situations such as admin requests, AJAX, cron, REST requests, and WP-CLI usage.

Headers, SEO, and Caching

When a visitor is blocked, the plugin sends a proper 503 Service Unavailable response.

It also sends headers intended to keep the blocked response out of caches and search results, including:

• Retry-After: 3600
• X-Robots-Tag: noindex, nofollow, nosnippet, noarchive, noimageindex
• strong no-cache headers
• CDN no-store headers

If Cloudflare is being used, the plugin adds CF-IPCountry to the Vary header so caches behave more safely.

What this means for you

• Blocked pages are not meant to be cached
• Search engines are told not to index blocked responses
• Allowed visitors are not affected by the blocking response

This is cleaner than redirect-based country blocking and avoids soft 404 style behavior.

Performance and Site Impact

The plugin runs early, before normal page rendering. It does not rely on front-end scripts for the blocking itself.

For allowed visitors, the plugin’s impact is minimal.

For blocked visitors, the plugin disables page, object, database, and minification caching for that request to avoid incorrect cached responses.

In normal use, the plugin is lightweight and quiet.

Translations

The plugin loads its text domain on plugins_loaded and is prepared for translation through standard WordPress localization.

That means plugin text such as default messages and settings labels can be translated in the normal WordPress way if translation files are present.

Real-World Behavior

This plugin is designed for practical, site-wide country blocking.

For ordinary visitors, it works reliably and predictably.

Like any web system that uses IP-based geolocation, visitors using VPNs, proxies, or similar services may appear to come from a different country. This is normal internet behavior, not something unique to this plugin.

That does not make the plugin weak. It simply means the plugin is a website-level country access tool, not a firewall or anti-circumvention system.

For many stores and websites, this is exactly the right level of control.

What This Plugin Does Not Do

To avoid confusion, this plugin does not:

• block only selected products
• block only shop pages
• create the /unavailable page for you
• redirect blocked visitors to another URL
• act as a firewall
• guarantee blocking against VPN or proxy users
• require cookies, tracking scripts, or analytics to work

Its job is simple: site-wide country blocking with a clean unavailable response.

Final Notes

WooCommerce Country Block is intentionally simple.

You choose which countries should be blocked. The plugin handles the rest.

It is designed to be predictable, privacy-friendly, lightweight, and easy to manage from one settings page.

No bloat. No tracking nonsense. Just a clear rule for who can and cannot access your website.

If you want, I can also turn this into clean HTML formatted for your docs page so you can paste it straight into WordPress.