Country ShieldBefore you start
You need a Shopify account that can install apps and customize the active theme. Keep your permanent myshopify.com domain available; a custom storefront domain is not used for installation.
Install Country Shield
Start from Shopify
Use the Country Shield App Store listing or an approved Shopify admin install surface. Country Shield does not ask you to type your store domain to begin installation.
Review requested permissions
Shopify shows the app authorization screen before installation. Approve the install to open the embedded Country Shield admin.
Confirm the store shown in the header
The merchant app displays the permanent store domain and current plan. Stop and contact support if the domain is not the store you intended to configure.
Create your first protection rule
Open Protection rules
Choose Denylist to block only selected countries. Choose Allowlist to block every country except your selections.
Add countries
Free stores can add two countries. Pro and Premium remove the country limit. Paid plans can also add supported regions or states.
Choose an action and scope
Start with Block and Whole store. Redirect and challenge are paid actions. Checkout-only applies the rule only on checkout paths.
Save changes
The right-side preview summarizes the policy. Country Shield enforces plan limits on the server when you save.
Enable the theme app extension
Rules are not applied to storefront traffic until Shopify loads the Country Shield app embed.
Open the theme editor
In Shopify admin, go to Online Store → Themes, then choose Customize for the active theme.
Open App embeds
Choose the App embeds icon in the theme editor. Find Country Shield and switch it on.
Save the theme
Use Shopify's Save control. Return to Country Shield and confirm that you enabled the extension.
Test without locking yourself out
- Open Protection rules and scroll to Test your rule.
- Select a country and use Preview decision. This evaluates the saved policy without creating a fake storefront request.
- Open the live storefront in a private browser window.
- Use a location you intentionally blocked and confirm the expected action.
- Return to Overview and confirm the setup checklist is complete.
When testing allowlist mode, include your own location before saving. When testing strict mode, confirm both an allowed and blocked location.
Understand actions and scope
Block
Matched visitors see the Country Shield interstitial. Paid plans may use a custom message.
Redirect
Matched visitors are sent to the HTTPS URL you enter. Verify that the target page does not redirect back to the blocked storefront.
Challenge
Matched visitors receive the supported verification path. This action is available on paid plans.
Whole store vs checkout only
Whole store checks every storefront path. Checkout only allows normal browsing and evaluates checkout paths.
Strict mode
Strict mode hides page content until an allow decision arrives. It fails open after a short timeout so a Country Shield outage does not leave the storefront permanently hidden.
Plans and Shopify billing
Open Billing inside Country Shield to compare plans. Shopify hosts plan selection and charge approval. Charges appear on the Shopify invoice, and merchants can upgrade or downgrade without reinstalling the app.
- Free includes two denylisted countries, a 7-day allowlist trial, and basic blocking.
- Pro adds unlimited countries, regions, paid actions, analytics, strict mode, and custom messaging.
- Premium adds ASN/IP rules, Cloudflare sync, and provider-dependent anonymous traffic controls.
Connect Cloudflare on Premium
Cloudflare edge sync is optional. It adds earlier country enforcement before a request reaches Shopify, while the Country Shield theme extension continues to enforce the complete saved policy.
Confirm the Shopify hostname is proxied
In Cloudflare DNS, use a Proxied CNAME from your custom storefront hostname to shops.myshopify.com. Cloudflare calls this Shopify Orange-to-Orange (O2O) routing. Follow Cloudflare’s Shopify provider guide. Do not enable Cloudflare’s account-wide Always Use HTTPS option for the O2O hostname because it can interfere with Shopify’s certificate validation path.
Create the least-privilege token
In Cloudflare, open My Profile → API Tokens → Create Token → Create Custom Token. Use a descriptive name such as Country Shield – example.com. Add exactly these permissions:
- Zone → Zone → Read
- Zone → Zone WAF → Edit (called Zone WAF Write in Cloudflare’s API documentation)
Under Zone Resources, choose Include → Specific zone → your storefront domain. Do not choose all zones and do not use the Global API Key. Leave Client IP filtering blank unless Country Shield support has supplied a fixed service IP. Avoid a short token expiration if you want automatic rule sync to continue. Review Cloudflare’s token instructions.
Copy the token immediately
Choose Continue to summary → Create Token. Cloudflare shows the token secret once. Copy it directly into a password manager or the Country Shield connection form. Never email it, paste it into support chat, or store it in a shared document.
Find the Zone ID
Open the storefront domain in Cloudflare, go to Overview, and locate the API section near the bottom. Copy Zone ID, not Account ID. See Cloudflare’s Zone ID guide.
Connect and verify
In Country Shield, open Cloudflare, paste the Zone ID and token, and choose Connect and sync. After it succeeds, Cloudflare should contain a security rule named Country Shield — managed geo block. Find it under Security → Security rules, or Security → WAF → Custom rules in the older dashboard.
What synchronizes to Cloudflare
Country Shield mirrors country allowlist and denylist logic. A Country Shield block becomes a Cloudflare block; Challenge becomes Managed Challenge. Verified search bots remain allowed. Redirect and checkout-only policies pause and remove the edge rule so their exact behavior can continue through the storefront app embed. Regions, ASN, IP/CIDR, VPN, proxy, Tor, and custom messages also remain in the storefront check. Country Shield edits only its own managed rule and leaves your other Cloudflare rules untouched.
Automatic sync and token rotation
Saving protection rules automatically refreshes the connected Cloudflare rule. Sync now forces an immediate refresh. To rotate credentials, disconnect Country Shield first, create and connect a replacement token, verify a successful sync, and then revoke the old token in Cloudflare.
Disconnect safely
Choose Disconnect in Country Shield before revoking the Cloudflare token. Country Shield attempts to remove its managed rule and then deletes the encrypted credential. If the token was already revoked, manually remove the Country Shield rule in Cloudflare.
Troubleshooting
The app says “Not active yet”
Save a ruleset, enable Country Shield under App embeds in the active theme, save the theme, and confirm the setup step in the embedded app.
Shopify asks me to reconnect
The store's rotating offline token may have expired or become invalid. Use the reconnect action and approve the same scopes again.
A paid plan still shows Free
Return from Shopify's hosted plan selection page and wait for verification. If the plan does not update, contact support with the store domain and approximate approval time.
Cloudflare says the token cannot edit the zone
Confirm that the token has both Zone Read and Zone WAF Edit, and that Zone Resources includes the same specific domain whose Zone ID you pasted. Account ID and Zone ID are different.
The Cloudflare rule exists but traffic is unaffected
Confirm the custom Shopify hostname is proxied in Cloudflare DNS. A DNS-only record bypasses the merchant’s Cloudflare security rules. Also confirm that the saved Country Shield policy contains at least one country.
Cloudflare sync stopped after working
The token may have expired, been revoked, or lost access when a Cloudflare user or role changed. Disconnect and reconnect with a new restricted token. If the old token cannot remove the rule, remove the Country Shield rule manually before reconnecting.
The wrong country is detected
Country decisions rely on the visitor's public IP and the current GeoIP database. Corporate networks, mobile carriers, and VPNs can exit in another location.
VPN or Tor controls are unavailable
The Premium anonymous-IP provider database is not currently connected. Country and ASN rules remain available according to plan.