Country Product Blocking/ Block your product by country for Martfury

Country Product Block — Smart Geo-Targeting for Your MarketplaceControl Product Visibility by Customer Location with Automatic IP Detection

Show the right products to the right customers. Country Product Block uses advanced IP geolocation to automatically detect visitor location and display only products available in their country. Perfect for international marketplaces with region-specific inventory.

Version: 1.0.0
Author: Maryam International LLC (www.codeupp.xyz)
Compatibility: Botble CMS 7.3+, All Themes
Requires: Ecommerce Plugin

How Location Detection Works

The plugin uses multiple detection methods with automatic fallback:

1. IP Geolocation (Primary Method)

• MaxMind GeoIP2 Database (Offline, most reliable)
• Free IP-API.com (Online fallback)
• CloudFlare Country Header (If using CloudFlare CDN)

2. Detection Flow

1. Check CloudFlare header (HTTP_CF_IPCOUNTRY) → Instant 2. Check MaxMind GeoIP2 database (local) → Fast 3. Fallback to IP-API.com (free API) → Reliable 4. Cache result for 24 hours per IP → Performance

3. Admin Override

• Admin can manually test by selecting a country from the admin bar
• Session-based override for testing without VPN

Key Features

FeatureDescription

Auto Country Detection

Detects visitor country from IP address automatically

Multi-Provider Fallback

CloudFlare → MaxMind → IP-API with smart caching

Admin Toggle

Enable/disable country filtering globally with one click

Dynamic Country List

Uses active countries from your theme/ecommerce settings

Vendor Control

Sellers assign countries to their own products

Admin Control

Admin assigns countries to inhouse products

Bulk Assignment

Assign multiple products to countries at once

Homepage Filtering

Only shows products available in visitor's country

Category Filtering

Category pages respect country restrictions

Search Filtering

Search results filtered by country

Performance Optimized

IP results cached, minimal database queries

Testing Mode

Admin can test different countries without VPN

How It WorksFor Customers (Automatic)

1. Customer visits your website from India
2. Plugin detects IP address → Country: India
3. Homepage shows only products assigned to India
4. If no country assigned to product → product shows everywhere (default behavior)

For Admin

1. Go to Admin → Country Product Block → Settings
2. Toggle "Enable Country Filtering" → ON
3. Select countries from the active country list
4. Go to Products → Edit Product
5. Assign countries in the "Available Countries" section
6. Save → Product now visible only in selected countries

For Vendors/Sellers

1. Go to Vendor Dashboard → Products → Edit Product
2. Scroll to "Available Countries" section
3. Select countries where this product should be visible
4. Save → Product filtered by country on storefront

InstallationStep 1: Upload Plugin

Copy the country-product-block folder to:

platform/plugins/country-product-block

Step 2: Install Dependencies

Run in your project root:

composer require geoip2/geoip2

Step 3: Activate Plugin

1. Go to Admin → Plugins
2. Find "Country Product Block"
3. Click Activate
4. Migrations run automatically

Step 4: Download GeoIP Database (Optional but Recommended)

For offline IP detection (faster and more reliable):

1. Sign up for free MaxMind account: https://www.maxmind.com/en/geolite2/signup
2. Download GeoLite2-Country.mmdb
3. Upload to: storage/app/geoip/GeoLite2-Country.mmdb

Without GeoIP database: Plugin uses free IP-API.com (works fine, requires internet)

Admin PanelSettings Page

Admin → Country Product Block → Settings

• Enable Country Filtering — Toggle ON/OFF (master switch)
• Active Countries — Shows all countries from your theme settings
• Detection Method — Displays current detection method being used
• Test Country — Select a country to test without VPN (session-based)
• Clear IP Cache — Clear cached IP detection results

Product Assignment

Admin → Products → Edit Product

New section: "Available Countries"

• Multi-select dropdown with all active countries
• Leave empty = product visible everywhere
• Select countries = product visible only in those countries

Bulk Assignment

Admin → Country Product Block → Bulk Assign

• Select multiple products
• Assign to one or more countries
• Overwrite or append to existing assignments

Vendor PanelProduct Assignment

Vendor Dashboard → Products → Edit Product

New section: "Available Countries"

• Same functionality as admin
• Vendors control their own products
• Cannot see/edit other vendors' assignments

Technical DetailsDatabase Tables

cpb_product_countries

• id — Primary key
• product_id — Product ID
• country_code — ISO 2-letter country code (IN, AE, US, GB, etc.)
• created_at, updated_at

cpb_settings

• Stores plugin settings (enabled/disabled, active countries)

IP Detection Cache

• Cached in Laravel cache for 24 hours
• Key format: country_ip_{ip_address}
• Reduces API calls and improves performance

Hooks & Filters

The plugin hooks into:

• Product query builder (filters by country)
• Homepage product display
• Category page queries
• Search results
• Related products
• Flash sales (if plugin installed)

Detection Methods Explained1. CloudFlare Header (Fastest)

If your site uses CloudFlare CDN:

• CloudFlare adds HTTP_CF_IPCOUNTRY header to every request
• Contains 2-letter country code (e.g., "IN", "AE", "US")
• Instant detection, no API calls needed

2. MaxMind GeoIP2 (Most Reliable)

If you upload the GeoLite2 database:

• Offline detection from local database file
• 99.8% accuracy for country-level detection
• No external API calls = faster and more reliable
• Free database updated monthly

3. IP-API.com (Free Fallback)

If CloudFlare and MaxMind unavailable:

• Free API with 45 requests/minute limit
• Reliable and accurate
• Results cached for 24 hours to avoid hitting limits

4. Default Behavior

If all methods fail:

• Plugin shows all products (no filtering)
• Logs error for admin review
• Graceful degradation — site continues working

Use CasesInternational Marketplace

• Sell electronics in US and UAE only
• Sell clothing in India and UK only
• Customers see only products available in their region

Region-Specific Inventory

• Product A available in India, UAE, Saudi Arabia
• Product B available in US, UK, Canada
• Automatic filtering based on visitor location

Compliance & Restrictions

• Certain products cannot be sold in specific countries
• Assign products to compliant countries only
• Automatic enforcement via IP detection

Multi-Vendor Regional Control

• Vendor A sells only in Middle East (AE, SA, KW)
• Vendor B sells only in Europe (UK, DE, FR)
• Each vendor controls their own product regions

Testing Without VPN

Admin Panel → Country Product Block → Settings → Test Country

1. Select a country from dropdown (e.g., "United States")
2. Click "Apply Test Country"
3. Visit homepage as a regular visitor
4. You'll see products as if you're browsing from that country
5. Click "Clear Test Country" to return to your real location

Session-based: Only affects your admin session, not other visitors.

Performance Optimization

• IP results cached for 24 hours — reduces API calls
• Database queries optimized — uses eager loading and indexes
• Conditional filtering — only filters when toggle is ON
• Graceful fallback — if detection fails, shows all products

FAQ

Q: What happens if I don't assign countries to a product?
A: Product is visible everywhere (default behavior).

Q: What if customer uses VPN?
A: Plugin detects VPN exit node country. Customer sees products for that country.

Q: Does this work with marketplace plugin?
A: Yes! Both admin and vendors can assign countries to their products.

Q: What if IP detection fails?
A: Plugin shows all products (no filtering). Site continues working normally.

Q: Can I test without VPN?
A: Yes! Use the "Test Country" feature in admin settings.

Q: Does this slow down my site?
A: No. IP detection is cached for 24 hours. First visit = 1 API call, then cached.

Q: Do I need MaxMind database?
A: No, but recommended. Plugin works fine with free IP-API.com fallback.

Changelogv1.0.0 — March 2026

Initial Release:

• IP geolocation with CloudFlare, MaxMind, and IP-API fallback
• Admin toggle to enable/disable country filtering
• Dynamic country list from theme settings
• Product country assignment for admin and vendors
• Homepage, category, search filtering
• IP result caching for performance
• Test country mode for admin
• Bulk product assignment
• Graceful fallback if detection fails

Support

For support, customization, or feature requests:

• Website: www.codeupp.xyz
• Email: maryaminternationalllc@gmail.com

Show the right products to the right customers, automatically.
Country Product Block — Smart geo-targeting for modern marketplaces.

Developed with precision by Maryam International LLC — Powering marketplaces worldwide.